Documentation Powered by ReDoc

Platform Repository Service (develop-SNAPSHOT)

Download OpenAPI specification:Download

E-mail: thomas.yu@sagebionetworks.org License: Apache-2.0

Platform Repository Service - Sage Bionetworks Platform

Authentication

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Access Approval Services

The Access Approval services manage the fulfillment of Access Requirements, on a per-user basis.

Revoke all Access Approvals an accessor may have for a given Access Requirement.

Revoke all Access Approvals an accessor may have for a given Access Requirement.

This service is only available to the ACT. Note: requirementId must be the ID of an ACT AccessRequirement.

Authorizations:
bearerAuth
query Parameters
accessorId
required
string

The user whose access is being revoked

requirementId
required
string

The ID of the Access Requirement.

Responses

Response samples

Content type
application/json
"string"

Create an Access Approval, thereby fulfilling an Access Requirement for a given user.

Create an Access Approval, thereby fulfilling an Access Requirement for a given user.

Self-signed Access Approvals may be generated by the user being approved. ACT Access Approvals may be generated only by the Synapse Access and Compliance Team (ACT).

Since an Access Requirement may apply to multiple entities, fulfilling an Access Requirement provides access to all entities restricted by the fulfilled requirement.

Authorizations:
bearerAuth
Request Body schema: application/json

the Access Approval to create

accessorId
string

The ID of the principal (user or group) approved for access

createdBy
string

The user that created this object.

createdOn
string

The date this object was created.

etag
string (Etag)

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.

expiredOn
string

The date this object will be expired.

id
integer

The unique immutable ID

modifiedBy
string

The user that last modified this object.

modifiedOn
string

The date this object was last modified.

requirementId
integer

The ID of the Access Requirement.

requirementVersion
integer

The version of the Access Requirement.

state
string (ApprovalState)
Enum: "APPROVED" "REVOKED"

JSON enum for the state of AccessApproval

submitterId
string

The user who performed the necessary action(s) to gain this approval.

Responses

Request samples

Content type
application/json
{
  • "accessorId": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "expiredOn": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "requirementId": 12345,
  • "requirementVersion": 12345,
  • "state": "APPROVED",
  • "submitterId": "..."
}

Response samples

Content type
application/json
{
  • "accessorId": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "expiredOn": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "requirementId": 12345,
  • "requirementVersion": 12345,
  • "state": "APPROVED",
  • "submitterId": "..."
}

Delete an Access Approval. Deprecated

Delete a selected Access Approval. This service is only available to the ACT.

Authorizations:
bearerAuth
path Parameters
approvalId
required
string

The ID of the approval.

Responses

Retrieving an AccessApproval given its ID.

Retrieving an AccessApproval given its ID.

Authorizations:
bearerAuth
path Parameters
approvalId
required
string

The ID of the approval.

Responses

Response samples

Content type
application/json
{
  • "accessorId": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "expiredOn": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "requirementId": 12345,
  • "requirementVersion": 12345,
  • "state": "APPROVED",
  • "submitterId": "..."
}

Retrieving a page of AccessorGroup.

Retrieving a page of AccessorGroup.

This service is only available for ACT. ACT can filter on AccessRequirementId, submitterId, and expiredOn by setting the associated fields in AccessorGroupRequest.'

Authorizations:
bearerAuth
Request Body schema: application/json
accessRequirementId
string

The condition to filter by AccessRequirement. Use null to ignore this filter.'

expireBefore
string

The condition to filter by expiration. Use null to ignore this filter.'

nextPageToken
string

The token to get the next page result. Use null to get the first page.'

submitterId
string

The condition to filter by submitter. Use null to ignore this filter.'

Responses

Request samples

Content type
application/json
{
  • "accessRequirementId": "...",
  • "expireBefore": "...",
  • "nextPageToken": "...",
  • "submitterId": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "results": [
    ]
}

Retrieve a batch of AccessApprovalInfo for a single user.

Retrieve a batch of AccessApprovalInfo for a single user.

Authorizations:
bearerAuth
Request Body schema: application/json
accessRequirementIds
Array of strings

The ID of the access requirements.

userId
string

The ID of the user.

Responses

Request samples

Content type
application/json
{
  • "accessRequirementIds": [
    ],
  • "userId": "..."
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Fetches the notifications sent for an access requirement and a list of recipients.

Fetches the notifications sent for an access requirement and a list of recipients.

This service is only available for ACT.

Authorizations:
bearerAuth
Request Body schema: application/json
recipientIds
Array of numbers <= 25 items

The list of recipient ids.

requirementId
number

The id of the access requirement.

Responses

Request samples

Content type
application/json
{
  • "recipientIds": [
    ],
  • "requirementId": 12345
}

Response samples

Content type
application/json
{
  • "requirementId": 12345,
  • "results": [
    ]
}

Retrieve the Access Approvals for the given Team. Deprecated

Retrieve the Access Approvals for the given Team. This service is only available to the ACT.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

query Parameters
limit
integer [ 10 .. 50 ]
Default: 10

Limits the size of the page returned. For example, a page size of 10 require limit = 10. The maximum limit for this call is 50.

offset
integer >= 0
Default: 0

The index of the pagination offset. For a page size of 10, the first page would be at offset = 0, and the second page would be at offset = 10.

Responses

Response samples

Content type
application/json
"string"

Access Requirement Services

These services manage the Access Requirements/Restrictions (ARs) which may be placed on Entities, or Teams.

Add an Access Requirement to an Entity, or Team.

Add an Access Requirement to an Entity, or Team. This service may only be used by the Synapse Access and Compliance Team.

Authorizations:
bearerAuth
Request Body schema: application/json

the Access Requirement to create

accessType
string (ACCESS_TYPE)
Enum: "CREATE" "READ" "UPDATE" "DELETE" "CHANGE_PERMISSIONS" "DOWNLOAD" "UPLOAD" "PARTICIPATE" "SUBMIT" "READ_PRIVATE_SUBMISSION" "UPDATE_SUBMISSION" "DELETE_SUBMISSION" "TEAM_MEMBERSHIP_UPDATE" "SEND_MESSAGE" "CHANGE_SETTINGS" "MODERATE"

The enumeration of possible permission.

concreteType
string

Indicates which type of AccessRequirement this object represents. Provided by the system, the user may not set this field.

createdBy
string

The user that created this object. Provided by the system, the user may not set this field.

createdOn
string

The date this object was created. Provided by the system, the user may not set this field.

description
string

Short optional description for the AR. Limited to 50 characters.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an object is out-of-date.

id
number

The unique immutable ID. Provided by the system, the user may not set this field.

modifiedBy
string

The user that last modified this object. Provided by the system, the user may not set this field.

modifiedOn
string

The date this object was last modified. Provided by the system, the user may not set this field.

Array of objects (RestrictableObjectDescriptor)

The IDs of the items controlled by this Access Requirement. Required when creating or updating.

versionNumber
integer

The version number issued to this version on the object.

Responses

Request samples

Content type
application/json
{
  • "accessType": "SUBMIT",
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "subjectIds": [
    ],
  • "versionNumber": 12345
}

Response samples

Content type
application/json
{
  • "accessType": "SUBMIT",
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "subjectIds": [
    ],
  • "versionNumber": 12345
}

Delete an Access Requirement.

Delete an Access Requirement. This service may only be used by the Synapse Access and Compliance Team.

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

Responses

Response samples

Content type
application/json
"string"

Get an Access Requirement.

Get an Access Requirement to an Entity, or Team based on its ID.

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

Responses

Response samples

Content type
application/json
{
  • "accessType": "SUBMIT",
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "subjectIds": [
    ],
  • "versionNumber": 12345
}

Modify an existing Access Requirement.

Modify an existing Access Requirement.

This service may only be used by the Synapse Access and Compliance Team.

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

Request Body schema: application/json

The modified Access Requirement.

accessType
string (ACCESS_TYPE)
Enum: "CREATE" "READ" "UPDATE" "DELETE" "CHANGE_PERMISSIONS" "DOWNLOAD" "UPLOAD" "PARTICIPATE" "SUBMIT" "READ_PRIVATE_SUBMISSION" "UPDATE_SUBMISSION" "DELETE_SUBMISSION" "TEAM_MEMBERSHIP_UPDATE" "SEND_MESSAGE" "CHANGE_SETTINGS" "MODERATE"

The enumeration of possible permission.

concreteType
string

Indicates which type of AccessRequirement this object represents. Provided by the system, the user may not set this field.

createdBy
string

The user that created this object. Provided by the system, the user may not set this field.

createdOn
string

The date this object was created. Provided by the system, the user may not set this field.

description
string

Short optional description for the AR. Limited to 50 characters.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an object is out-of-date.

id
number

The unique immutable ID. Provided by the system, the user may not set this field.

modifiedBy
string

The user that last modified this object. Provided by the system, the user may not set this field.

modifiedOn
string

The date this object was last modified. Provided by the system, the user may not set this field.

Array of objects (RestrictableObjectDescriptor)

The IDs of the items controlled by this Access Requirement. Required when creating or updating.

versionNumber
integer

The version number issued to this version on the object.

Responses

Request samples

Content type
application/json
{
  • "accessType": "SUBMIT",
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "subjectIds": [
    ],
  • "versionNumber": 12345
}

Response samples

Content type
application/json
{
  • "accessType": "SUBMIT",
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "subjectIds": [
    ],
  • "versionNumber": 12345
}

Retrieve a page of subjects for a given Access Requirement ID.

Retrieve a page of subjects for a given Access Requirement ID.

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

query Parameters
nextPageToken
string

Next page

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "subjects": [
    ]
}

Convert an ACTAccessRequirement to a ManagedACTAccessRequirement.

Convert an ACTAccessRequirement to a ManagedACTAccessRequirement.

Only ACT member can perform this action.

Authorizations:
bearerAuth
Request Body schema: application/json
accessRequirementId
string

The ID of an ACTAccessRequirement.

currentVersion
number

The current version of the AccessRequirement. This field is used for concurrency check.

etag
string

The etag of the AccessRequirement. This field is used for concurrency check.

Responses

Request samples

Content type
application/json
{
  • "accessRequirementId": "...",
  • "currentVersion": 12345,
  • "etag": "..."
}

Response samples

Content type
application/json
{
  • "accessType": "SUBMIT",
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "subjectIds": [
    ],
  • "versionNumber": 12345
}

Retrieve paginated list of ALL Access Requirements associated with an entity.

Retrieve paginated list of ALL Access Requirements associated with an entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

query Parameters
limit
integer [ 10 .. 50 ]

Limits the size of the page returned. For example, a page size of 10 require limit = 10. The maximum limit for this call is 50.

offset
integer >= 0

The index of the pagination offset. For a page size of 10, the first page would be at offset = 0, and the second page would be at offset = 10.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Add a temporary access restriction that prevents access pending review by the Synapse ACT.

Add a temporary access restriction that prevents access pending review by the Synapse Access and Compliance Team. This service may be used only by an administrator of the specified entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Response samples

Content type
application/json
{
  • "accessType": "SUBMIT",
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": 12345,
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "subjectIds": [
    ],
  • "versionNumber": 12345
}

Retrieve paginated list of ALL Access Requirements associated with a Team.

Retrieve paginated list of ALL Access Requirements associated with a Team.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

query Parameters
limit
integer [ 10 .. 50 ]
Default: 10

Limits the size of the page returned. For example, a page size of 10 require limit = 10. The maximum limit for this call is 50.

offset
integer >= 0
Default: 0

The index of the pagination offset. For a page size of 10, the first page would be at offset = 0, and the second page would be at offset = 10.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Activity Services

The Activity model represents the main record of Provenance in Synapse. It is analygous to the Activity defined in the W3C Specification on Provenance.

Used & Generated By

Used links are stored directly in the Activity model object as an array of Used objects. There is a flag in Used that marks if it was "executed". Used is an interface that is implemented by two objects:

  • UsedEntity - For referencing Entities already stored in Synapse
  • UsedURL - For referencing URL-accessed resources stored outside of Synapse. In Provenance visualizations, some URLs are given a special icon, such as links to GitHub. Note: it is also possible to wrap a URL with a FileEntity if you want all the resources that come with Synapse entities.

wasGeneratedBy links are stored for each version of each Entity. Thus you update the entity with the activity id that generated it. You can ask the entity service which activity generated it, and conversely you can ask the activity service what entity versions were generatedBy a given activity.

Access Control for Activities

Access to Activity objects is dictated by the following rules:

  • READ - Granted to those users who can see a single Entity that was generated by this Activity.
  • UPDATE/DELETE - You must be the creator of the Activity to modify or delete it.
  • Setting generatedBy for an Entity (see POST /entity) - You must be the creator of the activity to connect it to an Entity. (The Entity services allow you to specify an activityId that creates a generatedBy relationship between an Activity and an Entity.)

Create a new Activity

Create a new provenenance Activity. If the passed Activity object contains a Used array, you must set the concreteType field of each Used subclass.

Access Control: READ access is granted to those users who can see a single Entity that was generated by this Activity.

Authorizations:
bearerAuth
Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "used": [
    ]
}

Delete an Activity

Delete an Activity.

You must be the creator of the Activity to delete it.

Authorizations:
bearerAuth
path Parameters
id
required
string

The id of an Activity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Get an existing Activity.

Get an existing Activity

Granted to those users who can see a single Entity that was generated by this Activity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The id of an Activity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "used": [
    ]
}

Update an Activity.

Update an Activity

You must be the creator of the Activity to modify it.

Authorizations:
bearerAuth
path Parameters
id
required
string

The id of an Activity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "used": [
    ]
}

Get the Entities that were generatedBy an Activity.

Get the Entities that were generatedBy an Activity. Returns a PaginatedResults of Reference objects.

This service will return References to all generatedBy Entities, regardless of whether you have access to resolve them into full Entity objects.

Authorizations:
bearerAuth
path Parameters
id
required
string

The id of an Activity.

query Parameters
limit
integer >= 10
Default: 10

Limit of query

offset
integer >= 0
Default: 0

Offset of query

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Asynchronous Job Services

This is a generic set of services that provides support for both launching asynchronous jobs and monitoring the progress of jobs.

Launch new Asynchronous jobs.

This method is used to launch new jobs. The type of job that will be launched is determined by the passed

AsynchronousJobBody.

The following are the currently supported job types:

  • UploadToTableRequest
  • DownloadFromTableRequest

Note: Each job types has different access requirements.

Authorizations:
bearerAuth
Request Body schema: application/json
concreteType
string

Concrete Type

Responses

Request samples

Content type
application/json
{
  • "concreteType": "..."
}

Response samples

Content type
application/json
{
  • "changedOn": "...",
  • "errorDetails": "...",
  • "errorMessage": "...",
  • "etag": "...",
  • "exception": "...",
  • "jobCanceling": true,
  • "jobId": "...",
  • "jobState": "PROCESSING",
  • "progressCurrent": 12345,
  • "progressMessage": "...",
  • "progressTotal": 12345,
  • "requestBody": {
    },
  • "responseBody": {
    },
  • "runtimeMS": 12345,
  • "startedByUserId": 12345,
  • "startedOn": "..."
}

Get Asynchronous Job.

Once a job is launched its progress can be monitored by getting its status with this method.

Authorizations:
bearerAuth
path Parameters
jobId
required
string

The ID of a Asynchronous Job.

Responses

Response samples

Content type
application/json
{
  • "changedOn": "...",
  • "errorDetails": "...",
  • "errorMessage": "...",
  • "etag": "...",
  • "exception": "...",
  • "jobCanceling": true,
  • "jobId": "...",
  • "jobState": "PROCESSING",
  • "progressCurrent": 12345,
  • "progressMessage": "...",
  • "progressTotal": 12345,
  • "requestBody": {
    },
  • "responseBody": {
    },
  • "runtimeMS": 12345,
  • "startedByUserId": 12345,
  • "startedOn": "..."
}

Stop a Asynchronous Job.

Once a job is launched it can be cancelled if the job is set up to be cancelable.

Authorizations:
bearerAuth
path Parameters
jobId
required
string

The ID of a Asynchronous Job.

Responses

Certified User Services

To become a Synapse Certified User you must pass a test. The Synapse APIs include a service to provide the test and a service to submit a test result. There are also administrative services to retrieve the history of test submissions.

Set certification status

Setting certification status.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Synapse user.

Responses

Retrieve the Passing Record on the User Certification test for the given user.

Retrieve the Passing Record on the User Certification test for the given user.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Synapse user.

Responses

Response samples

Content type
application/json
{
  • "corrections": [
    ],
  • "passed": true,
  • "passedOn": "...",
  • "quizId": 12345,
  • "responseId": 12345,
  • "score": 12345,
  • "userId": "..."
}

Challenge Services

A Challenge is a special object that supplements a project, providing additional features specific to challenges.

Create a Challenge object, associated with a Project.

Create a Challenge object, associated with a Project. A participant Team must be specified. To create a Challenge one must have CREATE permission on the associated Project.

Authorizations:
bearerAuth
Request Body schema: application/json
etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.

projectId
string

The ID of the Project the challenge is used with.

participantTeamId
string

The ID of the Team which users join to participate in the Challenge

id
string

The ID of this Challenge object

Responses

Request samples

Content type
application/json
{
  • "etag": "32439w3qsdfw",
  • "projectId": "syn22222",
  • "participantTeamId": "333333",
  • "id": "4321"
}

Response samples

Content type
application/json
{
  • "etag": "32439w3qsdfw",
  • "projectId": "syn22222",
  • "participantTeamId": "333333",
  • "id": "4321"
}

List the Challenges for which the given participant is registered.

List the Challenges for which the given participant is registered. To be in the returned list the caller must have READ permission on the project associated with the Challenge.

Authorizations:
bearerAuth
query Parameters
participantId
required
integer

Synapse user id

limit
integer [ 10 .. 100 ]
Default: 10

Maximum number of results returned

offset
integer >= 0
Default: 0

Index of the first result that must be returned

Responses

Response samples

Content type
application/json
{
  • "totalNumberOfResults": 12345,
  • "results": [
    ]
}

Retrieve a Challenge given its ID.

Retrieve a Challenge given its ID. To retrieve a Challenge one must have READ permission on the associated Project.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

Responses

Response samples

Content type
application/json
{
  • "etag": "32439w3qsdfw",
  • "projectId": "syn22222",
  • "participantTeamId": "333333",
  • "id": "4321"
}

Update a Challenge.

Update a Challenge. The caller must have UPDATE permission on the project associated with the Challenge. It is not permitted to change the project associated with a Challenge.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

Request Body schema: application/json
etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.

projectId
string

The ID of the Project the challenge is used with.

participantTeamId
string

The ID of the Team which users join to participate in the Challenge

id
string

The ID of this Challenge object

Responses

Request samples

Content type
application/json
{
  • "etag": "32439w3qsdfw",
  • "projectId": "syn22222",
  • "participantTeamId": "333333",
  • "id": "4321"
}

Response samples

Content type
application/json
{
  • "etag": "32439w3qsdfw",
  • "projectId": "syn22222",
  • "participantTeamId": "333333",
  • "id": "4321"
}

Delete a Challenge.

Delete a Challenge. The caller must have DELETE permission on the project associated with the Challenge.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

Responses

List the Teams registered for a Challenge.

List the Teams registered for a Challenge. You must have READ permission in the associated Project to make this request.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Maximum number of results returned

offset
integer >= 0
Default: 0

Index of the first result that must be returned

Responses

Response samples

Content type
application/json
{
  • "totalNumberOfResults": 12345,
  • "results": [
    ]
}

Register a Team with a Challenge.

Register a Team with a Challenge. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) and be an administrator on the Team being registered.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

Request Body schema: application/json
id
string

The ID of this ChallengeTeam object

teamId
string

The ID of the Team

challengeId
string

The ID of the Challenge

message
string

A descriptive message for the Team in the context of the Challenge. Limited to 500 characters.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.

Responses

Request samples

Content type
application/json
{
  • "id": "1111",
  • "teamId": "222222",
  • "challengeId": "3423",
  • "message": "Testing",
  • "etag": "33492273ssdf"
}

Response samples

Content type
application/json
{
  • "id": "1111",
  • "teamId": "222222",
  • "challengeId": "3423",
  • "message": "Testing",
  • "etag": "33492273ssdf"
}

Update a Challenge Team.

Update a Challenge Team. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) and be an administrator on the associated Team.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

challengeTeamId
required
integer

The ID of the challenge team.

Request Body schema: application/json
id
string

The ID of this ChallengeTeam object

teamId
string

The ID of the Team

challengeId
string

The ID of the Challenge

message
string

A descriptive message for the Team in the context of the Challenge. Limited to 500 characters.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.

Responses

Request samples

Content type
application/json
{
  • "id": "1111",
  • "teamId": "222222",
  • "challengeId": "3423",
  • "message": "Testing",
  • "etag": "33492273ssdf"
}

Response samples

Content type
application/json
{
  • "id": "1111",
  • "teamId": "222222",
  • "challengeId": "3423",
  • "message": "Testing",
  • "etag": "33492273ssdf"
}

List the participants registered for a Challenge.

List the participants registered for a Challenge. The caller must have READ permission on the project associated with the Challenge.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

query Parameters
affiliated
boolean

If affiliated=true, return just participants affiliated with some registered Team. If false, return those not affiliated with any registered Team. If omitted return all participants.

limit
integer [ 10 .. 100 ]
Default: 10

Maximum number of results returned

offset
integer >= 0
Default: 0

Index of the first result that must be returned

Responses

Response samples

Content type
application/json
{
  • "totalNumberOfResults": 12345,
  • "results": [
    ]
}

List the Teams that caller can register for the Challenge.

List the Teams that caller can register for the Challenge, i.e. Teams on which the caller is an administrator and which are not already registered. The caller must have READ permission on the project associated with the Challenge to make this request.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Maximum number of results returned

offset
integer >= 0
Default: 0

Index of the first result that must be returned

Responses

Response samples

Content type
application/json
{
  • "totalNumberOfResults": 12345,
  • "results": [
    ]
}

List the Teams under which the given submitter may submit to the Challenge.

List the Teams under which the given submitter may submit to the Challenge, i.e. the Teams on which the user is a member and which are registered for the Challenge.

Authorizations:
bearerAuth
path Parameters
challengeId
required
integer

The ID of the challenge.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Maximum number of results returned

offset
integer >= 0
Default: 0

Index of the first result that must be returned

Responses

Response samples

Content type
application/json
{
  • "totalNumberOfResults": 12345,
  • "results": [
    ]
}

De-register a Team from a Challenge.

De-register a Team from a Challenge. You must be a member of the Challenge's participant Team (i.e. you must be already registered for the Challenge) and be an administrator on the Team being de-registered.

Authorizations:
bearerAuth
path Parameters
challengeTeamId
required
integer

The ID of the challenge team.

Responses

Retrieve a Challenge given the ID of its associated Project.

Retrieve a Challenge given the ID of its associated Project. To retrieve a Challenge one must have READ permission on the Project.

Authorizations:
bearerAuth
path Parameters
id
required
string

Synapse Project id

Responses

Response samples

Content type
application/json
{
  • "etag": "32439w3qsdfw",
  • "projectId": "syn22222",
  • "participantTeamId": "333333",
  • "id": "4321"
}

Data Access Services

Some data in Synapse are governed by an ACTAccessRequirement. To gain access to these data, a user must meet all requirements specified in the ACTAccessRequirement.

These services provide the APIs for users to create request to gain access to controlled data, and APIs for the ACT to review and grant access to users.

Return approved data access submissions

Return the research project info for approved data access submissions, ordered by submission modified-on date, ascending

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

Request Body schema: application/json
accessRequirementId
string

The ID of an AccessRequirement.

nextPageToken
string

The token to get the next page result.

Responses

Request samples

Content type
application/json
{
  • "accessRequirementId": "...",
  • "nextPageToken": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "results": [
    ]
}

Retrieve the Request for update.

Retrieve the Request for update.

If one does not exist, an Request with some re-filled information is returned. If a submission associated with the request is approved, and the requirement requires renewal, a refilled Renewal is returned. Only the owner of the request can perform this action.

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

Responses

Response samples

Content type
application/json
{
  • "accessRequirementId": "...",
  • "accessorChanges": [
    ],
  • "attachments": [
    ],
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": 12345,
  • "ducFileHandleId": "...",
  • "etag": "...",
  • "id": "...",
  • "irbFileHandleId": "...",
  • "modifiedBy": "...",
  • "modifiedOn": 12345,
  • "researchProjectId": "..."
}

Retrieve an existing ResearchProject that the user owns.

Retrieve an existing ResearchProject that the user owns.

If none exists, a ResearchProject with some re-filled information is returned to the user. Only the owner of the researchProject can perform this action.

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

Responses

Response samples

Content type
application/json
{
  • "accessRequirementId": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "id": "...",
  • "institution": "...",
  • "intendedDataUseStatement": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "projectLead": "..."
}

Retrieve an access requirement status for a given access requirement ID.

Retrieve an access requirement status for a given access requirement ID.

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

Responses

Response samples

Content type
application/json
{
  • "accessRequirementId": "...",
  • "concreteType": "...",
  • "expiredOn": "...",
  • "isApproved": true
}

Retrieve a list of submissions for a given access requirement ID.

Retrieve a list of submissions for a given access requirement ID.

Only ACT member can perform this action.

Authorizations:
bearerAuth
path Parameters
requirementId
required
string

the ID of the requirement.

Request Body schema: application/json
accessRequirementId
string

The ID of an AccessRequirement.

filterBy
string (SubmissionState)
Enum: "SUBMITTED" "APPROVED" "REJECTED" "CANCELLED"

The state of a Submission.

isAscending
boolean

If true, order the returned result in ascending order. Otherwise, order the returned result in descending order.

nextPageToken
string

The token to get the next page result.

orderBy
string (SubmissionOrder)
Enum: "CREATED_ON" "MODIFIED_ON"

Submission Order

Responses

Request samples

Content type
application/json
{
  • "accessRequirementId": "...",
  • "filterBy": "APPROVED",
  • "isAscending": true,
  • "nextPageToken": "...",
  • "orderBy": "MODIFIED_ON"
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "results": [
    ]
}

Discussion Services

Discussions in Synapse are captured in the Project's Forum. Each Project has a Forum. Each Forum has a set of Moderators. The Moderators manage the content of the Forum.

This API is used to get N number of threads that belongs to projects user can view and references the given entity.

This API is used to get N number of threads that belongs to projects user can view and references the given entity.

Target users: anyone who has READ permission to the entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

query Parameters
ascending
boolean

The direction of sort: true for ascending, and false for descending

limit
number [ 10 .. 20 ]
Default: 10

Limits the size of the page returned. For example, a page size of 10 require limit = 10. The maximum Limit for this call is 20.'

offset
number >= 0
Default: 0

The index of the pagination offset. For a page size of 10, the first page would be at offset = 0, and the second page would be at offset = 10.'

sort
string
Enum: "NUMBER_OF_REPLIES" "NUMBER_OF_VIEWS" "PINNED_AND_LAST_ACTIVITY" "THREAD_TITLE"

The field to sort the resulting threads on. Available options DiscussionThreadOrder

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Get number of threads that belong to projects user can view and references the given entity.

This API is used to get list of entity and count pairs, with count is the number of threads that belong to projects user can view and references the given entity.

Target users: anyone who has READ permission to the project.

Authorizations:
bearerAuth
Request Body schema: application/json

The requested list. Limit size 20.

idList
Array of strings

List of Entity Ids

Responses

Request samples

Content type
application/json
{
  • "idList": [
    ]
}

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Get a Forum.

This API is used to get the Forum''s metadata for a given its ID.

Target users: anyone who has READ permission to the project.'

Authorizations:
bearerAuth
path Parameters
forumId
required
string

The ID of the Forum.

Responses

Response samples

Content type
application/json
{
  • "etag": "...",
  • "id": "...",
  • "projectId": "..."
}

Returns a page of Forum moderators.

Returns a page of moderators for a given forum ID.

Target users: anyone who has READ permission to the project.

Authorizations:
bearerAuth
path Parameters
forumId
required
string

The ID of the Forum.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Limits the size of the page returned.

offset
integer >= 0
Default: 0

The index of the pagination offset. For a page size of 10, the first page would be at offset = 0, and the second page would be at offset = 10.'

Responses

Response samples

Content type
application/json
{
  • "totalNumberOfResults": 12345,
  • "results": [
    ]
}

Get the total number of threads for a Forum.

This API is used to get the total number of threads for a given forum ID.

Target users: anyone who has READ permission to the project.

Authorizations:
bearerAuth
path Parameters
forumId
required
string

The ID of the Forum.

query Parameters
filter
string
Enum: "DELETED_ONLY" "EXCLUDE_DELETED" "NO_FILTER"

Filter deleted or not deleted threads.

Responses

Response samples

Content type
application/json
{
  • "count": 12345
}

Get N number of threads for a Forum.

This API is used to get N number of threads for a given forum ID.

Target users: anyone who has READ permission to the project.'

Authorizations:
bearerAuth
path Parameters
forumId
required
string

The ID of a Forum.

query Parameters
ascending
boolean

The direction of sort: true for ascending, and false for descending

filter
string
Enum: "DELETED_ONLY" "EXCLUDE_DELETED" "NO_FILTER"

Filter deleted or not deleted threads.

limit
integer [ 10 .. 20 ]
Default: 10

Limits the size of the page returned. For example, a page size of 10 require limit = 10.

offset
number >= 0
Default: 0
  • The index of the pagination offset. For a page size of 10, the first page would be at offset = 0, and the second page would be at offset = 10.
sort
string
Enum: "NUMBER_OF_REPLIES" "NUMBER_OF_VIEWS" "PINNED_AND_LAST_ACTIVITY" "THREAD_TITLE"

The field to sort the resulting threads on.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Get the Forum of a Project.

This API is used to get the Forum's metadata for a given project ID.

Target users: anyone who has READ permission to the project.'

Authorizations:
bearerAuth
path Parameters
projectId
required
string

The ID of a Project.

Responses

Response samples

Content type
application/json
{
  • "etag": "...",
  • "id": "...",
  • "projectId": "..."
}

Create a new reply to a thread.

This API is used to create a new reply to a thread.

Target users: anyone who has READ permission to the project.

Authorizations:
bearerAuth
Request Body schema: application/json
  • This object contains information needed to create a reply.
messageMarkdown
string

The markdown of the Reply's message

threadId
string

The ID of the thread this Reply belongs to

Responses

Request samples

Content type
application/json
{
  • "messageMarkdown": "...",
  • "threadId": "..."
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "forumId": "...",
  • "id": "...",
  • "isDeleted": true,
  • "isEdited": true,
  • "messageKey": "...",
  • "modifiedOn": "...",
  • "projectId": "...",
  • "threadId": "..."
}

Delete Reply

This API is used to mark a reply as deleted.

Target users: only forum's moderator can mark a reply as deleted.

Authorizations:
bearerAuth
path Parameters
replyId
required
string

The ID of the Reply.

Responses

Get a Reply.

This API is used to get a reply and its statistic given its ID.

Target users: anyone who has READ permission to the project.

Authorizations:
bearerAuth
path Parameters
replyId
required
string

The ID of the Reply.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "forumId": "...",
  • "id": "...",
  • "isDeleted": true,
  • "isEdited": true,
  • "messageKey": "...",
  • "modifiedOn": "...",
  • "projectId": "...",
  • "threadId": "..."
}

Update the message of a reply.

This API is used to update the message of a reply.

Target users: only the author of the reply can update its message.'

Authorizations:
bearerAuth
path Parameters
replyId
required
string

The ID of the Reply.

Request Body schema: application/json
messageMarkdown
string

The new message markdown

Responses

Request samples

Content type
application/json
{
  • "messageMarkdown": "..."
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "forumId": "...",
  • "id": "...",
  • "isDeleted": true,
  • "isEdited": true,
  • "messageKey": "...",
  • "modifiedOn": "...",
  • "projectId": "...",
  • "threadId": "..."
}

Get the message URL of a reply.

This API is used to get the message URL of a reply. The message URL is the URL to download the file which contains the reply message.

Target users: anyone who has READ permission to the project. The resulting URL will be signed with Content-Type ="text/plain; charset=utf-8"; therefore, this header must be included with the GET on the URL.

Authorizations:
bearerAuth
query Parameters
messageKey
required
string

DiscussionReplyBundle.messageKey

Responses

Response samples

Content type
application/json
{
  • "messageUrl": "..."
}

Create a new thread in a forum.

This API is used to create a new thread in a forum.

Target users: anyone who has READ permission to the project.

Authorizations:
bearerAuth
Request Body schema: application/json
forumId
string

The ID of the forum this CreateThread belongs to

messageMarkdown
string

The markdown of the Thread's message

title
string

The title of the Thread

Responses

Request samples

Content type
application/json
{
  • "forumId": "...",
  • "messageMarkdown": "...",
  • "title": "..."
}

Response samples

Content type
application/json
{
  • "activeAuthors": [
    ],
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "forumId": "...",
  • "id": "...",
  • "isDeleted": true,
  • "isEdited": true,
  • "isPinned": true,
  • "lastActivity": "...",
  • "messageKey": "...",
  • "modifiedOn": "...",
  • "numberOfReplies": 12345,
  • "numberOfViews": 12345,
  • "projectId": "...",
  • "title": "..."
}

Delete a Thread.

This API is used to mark a thread as deleted.

Target users: only forum's moderator can mark a thread as deleted.

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

Responses

Get a thread.

This API is used to get a thread and its statistic given its ID.

Target users: anyone who has READ permission to the project.

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

Responses

Response samples

Content type
application/json
{
  • "activeAuthors": [
    ],
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "forumId": "...",
  • "id": "...",
  • "isDeleted": true,
  • "isEdited": true,
  • "isPinned": true,
  • "lastActivity": "...",
  • "messageKey": "...",
  • "modifiedOn": "...",
  • "numberOfReplies": 12345,
  • "numberOfViews": 12345,
  • "projectId": "...",
  • "title": "..."
}

Update the message of a thread.

This API is used to update the message of a thread.

Target users: only the author of the thread can update its message.'

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

Request Body schema: application/json
messageMarkdown
string

The new message markdown

Responses

Request samples

Content type
application/json
{
  • "messageMarkdown": "..."
}

Response samples

Content type
application/json
{
  • "activeAuthors": [
    ],
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "forumId": "...",
  • "id": "...",
  • "isDeleted": true,
  • "isEdited": true,
  • "isPinned": true,
  • "lastActivity": "...",
  • "messageKey": "...",
  • "modifiedOn": "...",
  • "numberOfReplies": 12345,
  • "numberOfViews": 12345,
  • "projectId": "...",
  • "title": "..."
}

Pin a Thread.

This API is used to mark a thread as pinned.

Target users: only forum's moderator can mark a thread as pinned.

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

Responses

Get N number of replies for a given thread ID.

This API is used to get N number of replies for a given thread ID.

Target users: anyone who has READ permission to the project.

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

query Parameters
ascending
boolean

The direction of sort: true for ascending, and false for descending

filter
required
string
Enum: "DELETED_ONLY" "EXCLUDE_DELETED" "NO_FILTER"

Filter deleted not deleted replies.

limit
integer [ 0 .. 100 ]
Default: 10

Limits the size of the page returned. For example, a page size of 10 require limit = 10.

offset
integer >= 0
Default: 0

The index of the pagination offset. For a page size of 10, the first page would be at offset = 0, and the second page would be at offset = 10.'

sort
string
Value: "CREATED_ON"

The field to sort the resulting replies on.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Get the total number of replies for a given Thread.

This API is used to get the total number of replies for a given thread ID.

Target users: anyone who has READ permission to the project.'

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

query Parameters
filter
required
string
Enum: "DELETED_ONLY" "EXCLUDE_DELETED" "NO_FILTER"

Filter deleted not deleted replies.

Responses

Response samples

Content type
application/json
{
  • "count": 12345
}

Restore a deleted thread.

This API is used to restore a deleted thread.

Target users: only forum's moderator can restore a deleted thread.

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

Responses

Response samples

Content type
application/json
"string"

Update the title of a Thread.

This API is used to update the title of a thread.

Target users: only the author of the thread can update its title.'

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

Request Body schema: application/json
title
string

New Thread Title

Responses

Request samples

Content type
application/json
{
  • "title": "..."
}

Response samples

Content type
application/json
{
  • "activeAuthors": [
    ],
  • "createdBy": "...",
  • "createdOn": "...",
  • "etag": "...",
  • "forumId": "...",
  • "id": "...",
  • "isDeleted": true,
  • "isEdited": true,
  • "isPinned": true,
  • "lastActivity": "...",
  • "messageKey": "...",
  • "modifiedOn": "...",
  • "numberOfReplies": 12345,
  • "numberOfViews": 12345,
  • "projectId": "...",
  • "title": "..."
}

Unpin a thread.

This API is used to unpin a thread.

Target users: only forum's moderator can unpin a thread.

Authorizations:
bearerAuth
path Parameters
threadId
required
string

The ID of a thread.

Responses

Get the message URL of a thread.

This API is used to get the message URL of a thread. The message URL is the URL to download the file which contains the thread message.

Target users: anyone who has READ permission to the project.

The resulting URL will be signed with Content-Type ="text/plain; charset=utf-8"; therefore, this header must be included with the GET on the URL.

Authorizations:
bearerAuth
query Parameters
messageKey
required
string

Message Key

Responses

Response samples

Content type
application/json
{
  • "messageUrl": "..."
}

Docker Commit Services

These services relate to the 'commits' to Docker repositories. Note that create, update and delete of the Docker repositories themselves are done using the Entity Services, for external/unmanaged repositories, or by direct integration with the Docker registry, for managed Docker repositories. Tagged commits for both managed and external/unmanaged repositories may be retrieved using the 'listDockerTags' API included in this service.

Add a commit (tag and digest) for an external/unmanaged Docker repository.

Add a commit (tag and digest) for an external/unmanaged Docker repository. (Commits for managed repositories are added via direct integration with the Synapse Docker registry.)

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Docker repository entity

Request Body schema: application/json

the new tag/digest pair for the repository

createdOn
string

The date this commit was created.

digest
string

A unique id for the commit, generated by hashing its content.

tag
string

A user supplied name for a specific version of a repository.

Responses

Request samples

Content type
application/json
{
  • "createdOn": "...",
  • "digest": "...",
  • "tag": "..."
}

List the tagged commits (tag/digest pairs) for the given Docker repository.

List the tagged commits (tag/digest pairs) for the given Docker repository. Only the most recent digest for each tag is returned since, following Docker's convention, a tag may be reassigned to a newer commit. The list may be sorted by date or tag. The default is to sort by date, descending (newest first).'

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Docker repository entity

query Parameters
ascending
boolean
Default: false

Ascending

limit
integer >= 0
Default: 20

pagination parameter, optional (default is 20)

offset
integer >= 0
Default: 0

pagination parameter, optional (default is 0)

sort
string

Sort results

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Doi Services

Provides REST APIs for managing Synapse DOIs.

Retrieves the DOI for the object and its associated DOI metadata.

Retrieves the DOI for the object and its associated DOI metadata. Note: this call calls an external API, which may impact performance To just retrieve the DOI association, see: GET /doi/association

Authorizations:
bearerAuth
query Parameters
id
required
string

The ID of the object to retrieve

type
required
string (ObjectType)
Enum: "ENTITY" "ENTITY_CONTAINER" "PRINCIPAL" "ACTIVITY" "EVALUATION" "EVALUATION_ROUND" "SUBMISSION" "EVALUATION_SUBMISSIONS" "FILE" "MESSAGE" "WIKI" "FAVORITE" "ACCESS_REQUIREMENT" "ACCESS_APPROVAL" "TEAM" "TABLE" "ACCESS_CONTROL_LIST" "PROJECT_SETTING" "VERIFICATION_SUBMISSION" "CERTIFIED_USER_PASSING_RECORD" "FORUM" "THREAD" "REPLY" "FORM_GROUP" "ORGANIZATION" "FORM_DATA" "ENTITY_VIEW" "USER_PROFILE" "DATA_ACCESS_REQUEST" "DATA_ACCESS_SUBMISSION" "DATA_ACCESS_SUBMISSION_STATUS" "MEMBERSHIP_INVITATION"

The type of the object

version
integer

The version number of the object

Responses

Response samples

Content type
application/json
{
  • "associatedBy": "...",
  • "associatedOn": "...",
  • "associationId": "...",
  • "doiUri": "...",
  • "doiUrl": "...",
  • "etag": "...",
  • "objectId": "Doi",
  • "objectType": "WIKI",
  • "objectVersion": 12345,
  • "updatedBy": "...",
  • "updatedOn": "...",
  • "creators": [
    ],
  • "publicationYear": 0,
  • "resourceType": {
    },
  • "titles": [
    ]
}

Retrieves the DOI for the object.

Retrieves the DOI for the object. Note: this call only retrieves the DOI association, if it exists. To retrieve the metadata for the object, see GET /doi'

Authorizations:
bearerAuth
query Parameters
id
required
string

The ID of the object to retrieve

type
required
string (ObjectType)
Enum: "ENTITY" "ENTITY_CONTAINER" "PRINCIPAL" "ACTIVITY" "EVALUATION" "EVALUATION_ROUND" "SUBMISSION" "EVALUATION_SUBMISSIONS" "FILE" "MESSAGE" "WIKI" "FAVORITE" "ACCESS_REQUIREMENT" "ACCESS_APPROVAL" "TEAM" "TABLE" "ACCESS_CONTROL_LIST" "PROJECT_SETTING" "VERIFICATION_SUBMISSION" "CERTIFIED_USER_PASSING_RECORD" "FORUM" "THREAD" "REPLY" "FORM_GROUP" "ORGANIZATION" "FORM_DATA" "ENTITY_VIEW" "USER_PROFILE" "DATA_ACCESS_REQUEST" "DATA_ACCESS_SUBMISSION" "DATA_ACCESS_SUBMISSION_STATUS" "MEMBERSHIP_INVITATION"

The type of the object

version
integer

The version number of the object

Responses

Response samples

Content type
application/json
{
  • "associatedBy": "...",
  • "associatedOn": "...",
  • "associationId": "...",
  • "doiUri": "...",
  • "doiUrl": "...",
  • "etag": "...",
  • "objectId": "Doi",
  • "objectType": "WIKI",
  • "objectVersion": 12345,
  • "updatedBy": "...",
  • "updatedOn": "...",
  • "creators": [
    ],
  • "publicationYear": 0,
  • "resourceType": {
    },
  • "titles": [
    ]
}

Asynchronously creates or updates a DOI in Synapse, with input metadata.

Asynchronously creates or updates a DOI in Synapse, with input metadata. Retrieve the results with GET /doi/async/get/{asyncToken}. This call may fail if the external DataCite API is down. If the failure is recoverable, it will retry automatically.'

Authorizations:
bearerAuth
Request Body schema: application/json

A request containing a DOI and its metadata to associate with a Synapse object

concreteType
string

concrete type

object (Doi)

JSON schema for fields associated with a DOI and its metadata.

Responses

Request samples

Content type
application/json
{
  • "concreteType": "...",
  • "doi": {
    }
}

Response samples

Content type
application/json
{
  • "token": "..."
}

Get the results of a call to POST /doi/async/start

Get the results of a call to POST /doi/async/start

Authorizations:
bearerAuth
path Parameters
asyncToken
required
string

The async job token from the create/update call

Responses

Response samples

Content type
application/json
{
  • "concreteType": "...",
  • "doi": {
    }
}

Retrieves the Synapse web portal URL to the object entered.

Retrieves the Synapse web portal URL to the object entered. Note: This call does not check to see if the object exists in Synapse.

Authorizations:
bearerAuth
query Parameters
id
required
string

The ID of the object to retrieve

redirect
boolean
Default: true

Whether to return the URL or redirect to the URL

type
required
string (ObjectType)
Enum: "ENTITY" "ENTITY_CONTAINER" "PRINCIPAL" "ACTIVITY" "EVALUATION" "EVALUATION_ROUND" "SUBMISSION" "EVALUATION_SUBMISSIONS" "FILE" "MESSAGE" "WIKI" "FAVORITE" "ACCESS_REQUIREMENT" "ACCESS_APPROVAL" "TEAM" "TABLE" "ACCESS_CONTROL_LIST" "PROJECT_SETTING" "VERIFICATION_SUBMISSION" "CERTIFIED_USER_PASSING_RECORD" "FORUM" "THREAD" "REPLY" "FORM_GROUP" "ORGANIZATION" "FORM_DATA" "ENTITY_VIEW" "USER_PROFILE" "DATA_ACCESS_REQUEST" "DATA_ACCESS_SUBMISSION" "DATA_ACCESS_SUBMISSION_STATUS" "MEMBERSHIP_INVITATION"

The type of the object

version
integer

The version number of the object

Responses

Response samples

Content type
application/json
"string"

Entity Bundle V2 Services

The Entity Bundle Services provide bundled access to Entities and their related data components. An EntityBundle can be used to create, fetch, or update an Entity and associated objects with a single web service request.

Get an entity and related data with a single POST.

Get an entity and related data with a single POST.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
includeAccessControlList
boolean

Include the AccessControlList for this Entity

includeAnnotations
boolean

Include Annotations associated with the Entity in the response.

includeBenefactorACL
boolean

Include the ACL of the Entity from which this Entity inherits its AccessControlList

includeDOIAssociation
boolean

Include DOIs associated with this Entity

includeEntity
boolean

Include the Entity in the response.

includeEntityPath
boolean

Include EntityHeaders for all Entities in this Entity's path

includeFileHandles
boolean

Include all FileHandles associated with this Entity.

includeFileName
boolean

If this Entity is a FileEntity, include its filename

includeHasChildren
boolean

Include boolean indicating whether this Entity has children

includePermissions
boolean

Include permissions of the current user on the entity.

includeRestrictionInformation
boolean

Include the RestrictionLevel of this Entity

includeRootWikiId
boolean

Include the id of the root Wiki associated with this Entity

includeTableBundle
boolean

If the Entity is a TableEntity, include Table specific metadata.

includeThreadCount
boolean

Include the number of discussion threads that mention this Entity

Responses

Request samples

Content type
application/json
{
  • "includeAccessControlList": true,
  • "includeAnnotations": true,
  • "includeBenefactorACL": true,
  • "includeDOIAssociation": true,
  • "includeEntity": true,
  • "includeEntityPath": true,
  • "includeFileHandles": true,
  • "includeFileName": true,
  • "includeHasChildren": true,
  • "includePermissions": true,
  • "includeRestrictionInformation": true,
  • "includeRootWikiId": true,
  • "includeTableBundle": true,
  • "includeThreadCount": true
}

Response samples

Content type
application/json
{
  • "accessControlList": {
    },
  • "annotations": {
    },
  • "benefactorAcl": {
    },
  • "doiAssociation": {
    },
  • "entity": {
    },
  • "entityType": "entityview",
  • "fileHandles": [
    ],
  • "fileName": "...",
  • "hasChildren": true,
  • "path": {
    },
  • "permissions": {
    },
  • "restrictionInformation": {
    },
  • "rootWikiId": "...",
  • "tableBundle": {
    },
  • "threadCount": 12345
}

Update an entity and associated components with a single PUT.

Update an entity and associated components with a single PUT. Specifically, this operation supports update of an Entity, its Annotations, and its ACL. Upon successful creation, an EntityBundle is returned containing the requested components, as defined by the partsMask in the request object.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

query Parameters
generatedBy
string

Generated by

Request Body schema: application/json

The EntityBundleCreate object containing the Entity and Annotations to update.

object (AccessControlList)

Contains list of principals who can access the data with the allowed types of access for each.

object (Annotations)

Annotations are additional key-value pair metadata that are associated with an object.

object (Entity)

This is the base interface that all Entities implement.

Responses

Request samples

Content type
application/json
{
  • "accessControlList": {
    },
  • "annotations": {
    },
  • "entity": {
    }
}

Response samples

Content type
application/json
{
  • "accessControlList": {
    },
  • "annotations": {
    },
  • "benefactorAcl": {
    },
  • "doiAssociation": {
    },
  • "entity": {
    },
  • "entityType": "entityview",
  • "fileHandles": [
    ],
  • "fileName": "...",
  • "hasChildren": true,
  • "path": {
    },
  • "permissions": {
    },
  • "restrictionInformation": {
    },
  • "rootWikiId": "...",
  • "tableBundle": {
    },
  • "threadCount": 12345
}

Get an entity at a specific version and its related data with a single POST.

Get an entity at a specific version and its related data with a single POST.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

versionNumber
required
integer

The version number of the Entity.

Request Body schema: application/json
includeAccessControlList
boolean

Include the AccessControlList for this Entity

includeAnnotations
boolean

Include Annotations associated with the Entity in the response.

includeBenefactorACL
boolean

Include the ACL of the Entity from which this Entity inherits its AccessControlList

includeDOIAssociation
boolean

Include DOIs associated with this Entity

includeEntity
boolean

Include the Entity in the response.

includeEntityPath
boolean

Include EntityHeaders for all Entities in this Entity's path

includeFileHandles
boolean

Include all FileHandles associated with this Entity.

includeFileName
boolean

If this Entity is a FileEntity, include its filename

includeHasChildren
boolean

Include boolean indicating whether this Entity has children

includePermissions
boolean

Include permissions of the current user on the entity.

includeRestrictionInformation
boolean

Include the RestrictionLevel of this Entity

includeRootWikiId
boolean

Include the id of the root Wiki associated with this Entity

includeTableBundle
boolean

If the Entity is a TableEntity, include Table specific metadata.

includeThreadCount
boolean

Include the number of discussion threads that mention this Entity

Responses

Request samples

Content type
application/json
{
  • "includeAccessControlList": true,
  • "includeAnnotations": true,
  • "includeBenefactorACL": true,
  • "includeDOIAssociation": true,
  • "includeEntity": true,
  • "includeEntityPath": true,
  • "includeFileHandles": true,
  • "includeFileName": true,
  • "includeHasChildren": true,
  • "includePermissions": true,
  • "includeRestrictionInformation": true,
  • "includeRootWikiId": true,
  • "includeTableBundle": true,
  • "includeThreadCount": true
}

Response samples

Content type
application/json
{
  • "accessControlList": {
    },
  • "annotations": {
    },
  • "benefactorAcl": {
    },
  • "doiAssociation": {
    },
  • "entity": {
    },
  • "entityType": "entityview",
  • "fileHandles": [
    ],
  • "fileName": "...",
  • "hasChildren": true,
  • "path": {
    },
  • "permissions": {
    },
  • "restrictionInformation": {
    },
  • "rootWikiId": "...",
  • "tableBundle": {
    },
  • "threadCount": 12345
}

Create an entity and associated components with a single POST.

Create an entity and associated components with a single POST. Specifically, this operation supports creation of an Entity, its Annotations, and its ACL.

Upon successful creation, an EntityBundle is returned containing the requested components, as defined by the partsMask in the request object.'

Authorizations:
bearerAuth
query Parameters
generatedBy
string

Generated By

Request Body schema: application/json
object (AccessControlList)

Contains list of principals who can access the data with the allowed types of access for each.

object (Annotations)

Annotations are additional key-value pair metadata that are associated with an object.

object (Entity)

This is the base interface that all Entities implement.

Responses

Request samples

Content type
application/json
{
  • "accessControlList": {
    },
  • "annotations": {
    },
  • "entity": {
    }
}

Response samples

Content type
application/json
{
  • "accessControlList": {
    },
  • "annotations": {
    },
  • "benefactorAcl": {
    },
  • "doiAssociation": {
    },
  • "entity": {
    },
  • "entityType": "entityview",
  • "fileHandles": [
    ],
  • "fileName": "...",
  • "hasChildren": true,
  • "path": {
    },
  • "permissions": {
    },
  • "restrictionInformation": {
    },
  • "rootWikiId": "...",
  • "tableBundle": {
    },
  • "threadCount": 12345
}

Entity Services

All data in Synapse is organize into Projects. These Projects can be further organized into hierarchical Folders. Finally, the data is then represented by FileEntities or Records (coming soon) that reside within Folders or directly within Projects. All these objects (Projects, Folders, FileEntities, and Records) are derived from a common object called Entity. The Entity Services provide the means to create, read, update, and delete Synapse Entities. There are also services for navigating the Entity hierarchies, setting Authorization rules, and Annotating Entities.

Create a new Entity.

Create a new Entity. This method is used to create Projects, Folders, FileEntities and Records (coming soon). The passed request body should contain the following fields:

  • name - Give your new entity a Name. Note: A name must be unique within the given parent, similar to a file in a folder.
  • parentId - The ID of the parent Entity, such as a Folder or Project. This field should be excluded when creating a Project.
  • concreteType - Indicates the type of Entity to create. The value should be one of the following: org.sagebionetworks.repo.model.Project, org.sagebionetworks.repo.model.Folder, or org.sagebionetworks.repo.model.FileEntity

Note: To create an Entity the caller must be granted the ACCESS_TYPE.CREATE on the parent Entity. Any authenticated caller can create a new Project (with parentId=null).

Service Limits

resource limit
The maximum number of children for a single parent entity 10 K

Authorizations:
bearerAuth
query Parameters
generatedBy
string

To track the Provenance of an Entity create, include the ID of the Activity that was created to track the change. For more information see: POST /activity. You must be the creator of the Activity used here.'

Request Body schema: application/json
concreteType
string

Indicates which implementation of Entity this object represents. It should be set to one of the following: org.sagebionetworks.repo.model.Project, org.sagebionetworks.repo.model.Folder, or org.sagebionetworks.repo.model.FileEntity.

createdBy
string

The ID of the user that created this entity.

createdOn
string

The date this entity was created.

description
string <= 1000 characters

The description of this entity.

etag
string (Etag)

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.

id
string

The unique immutable ID for this entity. A new ID will be generated for new Entities. Once issued, this ID is guaranteed to never change or be re-issued

modifiedBy
string

The ID of the user that last modified this entity.

modifiedOn
string

The date this entity was last modified.

name
string [ 1 .. 256 ] characters ^[a-zA-Z0-9 +.'(_)]*$

The name of this entity. Names may only contain: letters, numbers, spaces, underscores, hyphens, periods, plus signs, apostrophes, and parentheses

parentId
string

The ID of the Entity that is the parent of this Entity.

Responses

Request samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "Trial ' + (_) . 09",
  • "parentId": "..."
}

Response samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "Trial ' + (_) . 09",
  • "parentId": "..."
}

Deletes an Entity

Moves an entity in the trash can, if the skipTrashCan is set to true will flag the entity for purge and it will be deleted as soon as possible.

Note: To delete an Entity the caller must be granted the

ACCESS_TYPE.DELETE on the Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

query Parameters
skipTrashCan
boolean

If true the entity will be flag for priority purge and deleted as soon as possible

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Get an Entity

Get an Entity using its ID.

Note: To get an Entity the caller must be granted the ACCESS_TYPE.READ on the Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Response samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "Trial ' + (_) . 09",
  • "parentId": "..."
}

Update an entity.

Update an entity.

If the Entity is a FileEntity and the dataFileHandleId fields is set to a new value, then a new version will automatically be created for this update if the MD5 of the new file handle does not match the MD5 of the existing file handle or if the file handles do not have an MD5 set. You can also force the creation of a new version using the newVersion parameter

(see below).

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time an Entity is updated a new etag will be issued to the Entity. When an update is request, Synapse will compare the etag of the passed Entity with the current etag of the Entity. If the etags do not match, then the update will be rejected with a PRECONDITION_FAILED (412) response. When this occurs the caller should get the latest copy of the Entity (see: GET /entity/{id}) and re-apply any changes to the object, then re-attempt the Entity update. This ensure the caller has any changes applied by other users before applying their own changes.

Note: To update an Entity the caller must be granted the ACCESS_TYPE.UPDATE on the Entity.

Service Limits

resource limit
The maximum number of children for a single parent entity 10 K

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

query Parameters
generatedBy
string

To track the Provenance of an Entity update, include the ID of the Activity that was created to track the change. For more information see: POST /activity. You must be the creator of the Activity used here.'

newVersion
string

To force the creation of a new version for a versionable entity such as a FileEntity, include this optional parameter with a value set to true (i.e. newVersion=true). This parameter is ignored for entities of type

Table (See POST /entity/{id}/table/snapshot instead)

Request Body schema: application/json
concreteType
string

Indicates which implementation of Entity this object represents. It should be set to one of the following: org.sagebionetworks.repo.model.Project, org.sagebionetworks.repo.model.Folder, or org.sagebionetworks.repo.model.FileEntity.

createdBy
string

The ID of the user that created this entity.

createdOn
string

The date this entity was created.

description
string <= 1000 characters

The description of this entity.

etag
string (Etag)

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.

id
string

The unique immutable ID for this entity. A new ID will be generated for new Entities. Once issued, this ID is guaranteed to never change or be re-issued

modifiedBy
string

The ID of the user that last modified this entity.

modifiedOn
string

The date this entity was last modified.

name
string [ 1 .. 256 ] characters ^[a-zA-Z0-9 +.'(_)]*$

The name of this entity. Names may only contain: letters, numbers, spaces, underscores, hyphens, periods, plus signs, apostrophes, and parentheses

parentId
string

The ID of the Entity that is the parent of this Entity.

Responses

Request samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "Trial ' + (_) . 09",
  • "parentId": "..."
}

Response samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "Trial ' + (_) . 09",
  • "parentId": "..."
}

Determine if the caller have a given permission on a given Entity.

Determine if the caller have a given permission on a given Entity.

A User's permission on an Entity is a calculation based several factors including the permission granted by the Entity's ACL and the User's group membership. There might also be extra requirement for an Entity, such as special terms-of-use or special restrictions for sensitive data. This means a client cannot accurately calculate a User's permission on an Entity simply by inspecting the Entity's ACL. Instead, all clients should use this method to get the calculated permission a User has on an Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

query Parameters
accessType
string

The permission to check. Must be from: ACCESS_TYPE'

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "result": true
}

Delete the Access Control List (ACL) for a given Entity.

Delete the Access Control List (ACL) for a given Entity.

By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.

If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent''s benefactor. The ACL for a Project cannot be deleted.

Note: The caller must be granted ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to call this method.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Get the Access Control List (ACL) for a given entity.

Get the Access Control List (ACL) for a given entity.

Note: If this method is called on an Entity that is inheriting its permission from another Entity a NOT_FOUND (404) response will be generated. The error response message will include the Entity''s benefactor ID.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Create a new Access Control List (ACL), overriding inheritance.

Create a new Access Control List (ACL), overriding inheritance.

By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.

If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.

Note: The caller must be granted

ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to call this method.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
createdBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

creationDate
string

Created Date

etag
string

Synapse etag value

id
string

The entity id

modifiedBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

modifiedOn
string

UNUSED -- maintained only for backwards compatibility with archived objects

Array of objects (ResourceAccess)

The list of principals who can access the data with the allowed types of access for each.

Responses

Request samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Update an Entity's ACL.

Update an Entity's ACL.

Note: The caller must be granted

ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to call this method.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
createdBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

creationDate
string

Created Date

etag
string

Synapse etag value

id
string

The entity id

modifiedBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

modifiedOn
string

UNUSED -- maintained only for backwards compatibility with archived objects

Array of objects (ResourceAccess)

The list of principals who can access the data with the allowed types of access for each.

Responses

Request samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Get the annotations for an entity.

Get the annotations for an entity.

Note: The caller must be granted the ACCESS_TYPE.READ on the Entity, to get its annotations.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Response samples

Content type
application/json
{
  • "annotations": {
    },
  • "etag": "...",
  • "id": "..."
}

Update an Entity's annotations.

Update an Entity's annotations.

Note: The caller must be granted the ACCESS_TYPE.UPDATE on the Entity, to update its annotations.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
object

Additional metadata associated with the object. The key is the name of your desired annotations. The value is an object containing a list of string values (use empty list to represent no values for key) and the value type associated with all values in the list

etag
string

Etag of the object to which this annotation belongs. To update an AnnotationV2, this field must match the current etag on the object.

id
string

ID of the object to which this annotation belongs

Responses

Request samples

Content type
application/json
{
  • "annotations": {
    },
  • "etag": "...",
  • "id": "..."
}

Response samples

Content type
application/json
{
  • "annotations": {
    },
  • "etag": "...",
  • "id": "..."
}

Get an Entity's benefactor.

Get an Entity's benefactor.

The term 'benefactor' is used indicate which Entity an Entity inherits is ACL from. For example, a newly created Project will have its own ACL and therefore, it will be its own benefactor. A Folder will inherit its ACL (by default) from its containing Project so the Project will be the Folder's benefactor. This method will return the EntityHeader of an Entity's benefactor.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "benefactorId": 12345,
  • "createdBy": "...",
  • "createdOn": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "type": "...",
  • "versionLabel": "...",
  • "versionNumber": 12345
}

Change the.

Change the DataType of the given entity. The entity's DataType controls how the entity can be accessed. For example, an entity's DataType must be set to 'open_data' in order for anonymous to be allowed to access its contents.

Note: The caller must be a member of the 'Synapse Access and Compliance Team' (id=464532) in order to change an Entity's type to 'OPEN_DATA'. The caller must be granted UPDATED on the Entity to change the its type to any other value.

'
Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

query Parameters
type
required
string
Enum: "OPEN_DATA" "SENSITIVE_DATA"

Type of data

Responses

Response samples

Content type
application/json
{
  • "dataType": "OPEN_DATA",
  • "objectId": "...",
  • "objectType": "FORM_GROUP",
  • "updatedBy": "...",
  • "updatedOn": "..."
}

Get the FileHandles of the file currently associated with the current version of the Entity.

Get the FileHandles of the file currently associated with the current version of the Entity.

If a preview exists for the file then the handle of the preview and the file will be returned with this call.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a File Entity.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Get the URL of the preview file associated with the current version of a FileEntity.

Get the URL of the preview file associated with the current version of a FileEntity.

Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if the caller meets all of the download requirements.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a File Entity.

query Parameters
redirect
boolean

When set to false, the URL will be returned as text/plain instead of redirecting.

status
integer

Status

Responses

Response samples

Content type
application/json
"string"

Deletes the activity relationship for the current version of an Entity.

Deletes the activity relationship for the current version of an Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Get an existing activity for the current version of an Entity.

Get an existing activity for the current version of an Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json

Get an existing activity for the current version of an Entity.

object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "used": [
    ]
}

Sets the generatedBy relationship for the current version of an Entity.

Sets the generatedBy relationship for the current version of an Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

query Parameters
generatedBy
required
string

The id of the activity to connect to the entity. You must be the creator of the Activity used here.'

Request Body schema: application/json

Sets the generatedBy relationship for the current version of an Entity.

object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "used": [
    ]
}

Get the raw JSON for the given entity.

Get the raw JSON for the given entity. The resulting JSON can be used for the validation of a entity against a JsonSchema.

Note: The caller must be granted the ACCESS_TYPE.READ permission on the Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Response samples

Content type
application/json
{ }

Update the annotations of an entity using the raw JSON of the entity.

Update the annotations of an entity using the raw JSON of the entity.

See: GET entity/{id}/json to get the JSON of an entity.

Note: The caller must be granted the ACCESS_TYPE.UPDATE and ACCESS_TYPE.READ permission on the Entity.

'
Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
object (JSONObject)

Json Object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Get the full path of an Entity as a List of EntityHeaders.

Get the full path of an Entity as a List of EntityHeaders. The first EntityHeader will be the Root Entity, and the last EntityHeader will be the requested Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Response samples

Content type
application/json
{
  • "path": [
    ]
}

Get the list of permission that the caller has on a given Entity.

Get the list of permission that the caller has on a given Entity.

A User's permission on an Entity is a calculation based several factors including the permission granted by the Entity's ACL and the User's group membership. There might also be extra requirement for an Entity, such as special terms-of-use or special restrictions for sensitive data. This means a client cannot accurately calculate a User's permission on an Entity simply by inspecting the Entity''s ACL. Instead, all clients should use this method to get the calculated permission a User has on an Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Response samples

Content type
application/json
{
  • "canAddChild": true,
  • "canCertifiedUserAddChild": true,
  • "canCertifiedUserEdit": true,
  • "canChangePermissions": true,
  • "canChangeSettings": true,
  • "canDelete": true,
  • "canDownload": true,
  • "canEdit": true,
  • "canEnableInheritance": true,
  • "canModerate": true,
  • "canPublicRead": true,
  • "canUpload": true,
  • "canView": true,
  • "isCertificationRequired": true,
  • "isCertifiedUser": true,
  • "ownerPrincipalId": 12345
}

Clear the bound JSON schema from this Entity.

Clear the bound JSON schema from this Entity. The schema will no longer be used to validate this Entity or its children.

Note: The caller must be granted the DELETE permission on the Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Get information about a JSON schema bound to an Entity.

Get information about a JSON schema bound to an Entity. Note: Any child Entity that does not have a bound schema will inherit the first bound schema found in its hierarchy.

Note: The caller must be granted the READ permission on the Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "jsonSchemaVersionInfo": {
    },
  • "objectId": 12345,
  • "objectType": "entity"
}

Bind a JSON schema to an Entity.

Bind a JSON schema to an Entity. The bound schema will be used to validate the Entity''s metadata (annotations). Any child Entity that does not have a bound schema will inherit the first bound schema found in its hierarchy.

Only a single schema can be bound to an Entity at a time. If you have more than one schema to bind to an Entity you will need to create and bind a single composition schema using keywords such as 'anyOf', 'allOf' or 'oneOf' that defines how the schemas should be used for validation.

Note: The caller must be granted the UPDATE ermission on the Entity to bind.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json

The request identifies the JSON schema to bind.

entityId
string

The ID of the the entity.

schema$id
string

The $id of the JSON schema to bind to the entity. Note: If the $id includes a semantic version then entity will be bound to that specific version. If the $id excludes the semantic version then the entity will be bound to the latest version of that schema.

Responses

Request samples

Content type
application/json
{
  • "entityId": "...",
  • "schema$id": "..."
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "jsonSchemaVersionInfo": {
    },
  • "objectId": 12345,
  • "objectType": "entity"
}

Get the validation results of an Entity against its bound JSON schema.

Get the validation results of an Entity against its bound JSON schema. The validation of an Entity against its bound schema is automatic and eventually consistent. The validation results include the etag of the Entity at the time of the last validation. If the returned etag does not match the current etag of the Entity then the results should be considered out-of-date. If an Entity has not been validated for the first time, or if the Entity does not have a bound schema, this method will return a 404 (not-found). Keep checking for the latest validation results.

Note: The caller must be granted the READ permission on the Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

Responses

Response samples

Content type
application/json
{
  • "allValidationMessages": [
    ],
  • "isValid": true,
  • "objectEtag": "...",
  • "objectId": "...",
  • "objectType": "entity",
  • "schema$id": "...",
  • "validatedOn": "...",
  • "validationErrorMessage": "...",
  • "validationException": {
    }
}

Get a single page of invalid JSON schema validation results for a container Entity (Project or Folder).

Get a single page of invalid JSON schema validation results for a container Entity (Project or Folder). The validation of an Entity against its bound schema is automatic and eventually consistent. The validation results include the etag of the Entity at the time of the last validation. If the returned etag does not match the current etag of the Entity then the results should be considered out-of-date.

Note: The caller must be granted the READ permission on the container Entity. The results will only include children that the caller has the READ permission on.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the container Entity.

Request Body schema: application/json
containerId
string

The ID of the Entity container to get.

nextPageToken
string

Forward the returned 'nextPageToken' to get the next page of results.

Responses

Request samples

Content type
application/json
{
  • "containerId": "...",
  • "nextPageToken": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "page": [
    ]
}

Get the summary statistics of the JSON schema validation results for a single container Entity such as a Project or Folder.

Get the The summary statistics of the JSON schema validation results for a single container Entity such as a Project or Folder. Only direct children of the container are included in the results. The statistics include the total number of children in the container, and the counts for both the invalid and valid children. If an Entity has not been validated for the first time, or it does not have bound schema it will be counted as 'unknown'.

The validation of an Entity against its bound schema is automatic and eventually consistent. Keep checking this method to get the latest validation statistics for the given container.

Note: The caller must be granted the READ permission on the container Entity. The resulting statistics will only include children that the caller has the READ permission on.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the container Entity.

Responses

Response samples

Content type
application/json
{
  • "containerId": "...",
  • "generatedOn": "...",
  • "numberOfInvalidChildren": 12345,
  • "numberOfUnknownChildren": 12345,
  • "numberOfValidChildren": 12345,
  • "totalNumberOfChildren": 12345
}

Gets the temporary S3 credentials from STS for the given entity.

Gets the temporary S3 credentials from STS for the given entity. These credentials are only good for the bucket and base key specified by the returned credentials and expire 12 hours after this API is called.

The specified entity must be a folder with an STS-enabled storage location. If that storage location is external storage, you may request read-only or read-write permissions. If that storage location is Synapse storage, you must request read-only permissions.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Folder with an STS-enabled storage location.

query Parameters
permission
required
string
Enum: "read_only" "read_write"

Read-only or read-write permissions.

Responses

Response samples

Content type
application/json
{
  • "accessKeyId": "...",
  • "baseKey": "...",
  • "bucket": "...",
  • "expiration": "...",
  • "secretAccessKey": "...",
  • "sessionToken": "..."
}

Get the EntityHeader of an Entity given its ID.

Get the EntityHeader of an Entity given its ID. The EntityHeader is a light weight object with basic information about an Entity includes its type.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "benefactorId": 12345,
  • "createdBy": "...",
  • "createdOn": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "type": "...",
  • "versionLabel": "...",
  • "versionNumber": 12345
}

Get all versions of an Entity one page at a time.

Get all versions of an Entity one page at a time.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

query Parameters
limit
integer >= 10
Default: 10

Limits the number of entities that will be fetched for this page. When null it will default to 10.

offset
integer >= 0
Default: 0

The offset index determines where this page will start from. When null it will default to 0.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Delete a specific version of a FileEntity.

Delete a specific version of a FileEntity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity

versionNumber
required
integer

The version number of the Entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Get a specific version of an Entity.

Get a specific version of an Entity.

Note: Only the current version of the Entity can be used for an Entity update. Therefore, only the current version of the Entity will be returned with the actual etag. All older versions will be returned with an eTag '00000000-0000-0000-0000-000000000000'.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity

versionNumber
required
integer

The version number of the Entity.

Responses

Response samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "Trial ' + (_) . 09",
  • "parentId": "..."
}

Get an Entity's annotations for a specific version of a FileEntity.

Get an Entity's annotations for a specific version of a FileEntity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

versionNumber
required
integer

The version number of the Entity.

Responses

Response samples

Content type
application/json
{
  • "annotations": {
    },
  • "etag": "...",
  • "id": "..."
}

Updates the filehandle.

Updates the FileHandle associated with the FileEntity with the provided entity id and version.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

versionNumber
required
integer

The version number of the Entity.

Request Body schema: application/json
newFileHandleId
string

The id of the new file handle to be associated with the FileEntity. The user performing the request must be the owner of the file handle.

oldFileHandleId
string

The id of the file handle currently associated to the FileEntity. Used to avoid conflicting cuncurrent updates, if the id does not match the current file handle id the request will be rejected with a PRECONDITION_FAILED (412) response.

Responses

Request samples

Content type
application/json
{
  • "newFileHandleId": "...",
  • "oldFileHandleId": "..."
}

Response samples

Content type
application/json
"string"

Get the FileHandles of the file associated with a specific version of a FileEntity.

Get the FileHandles of the file associated with a specific version of a FileEntity.

If a preview exists for the file then the handle of the preview and the file will be returned with this call.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

versionNumber
required
integer

The version number of the Entity.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Get the URL of the preview file associated with a specific version of a FileEntity.

Get the URL of the preview file associated with a specific version of a FileEntity.

Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if the caller meets all of the download requirements.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

versionNumber
required
integer

The version number of the Entity.

query Parameters
redirect
boolean

When set to false, the URL will be returned as text/plain instead of redirecting.

Responses

Response samples

Content type
application/json
"string"

Get an existing activity for a specific version of an Entity.

Get an existing activity for a specific version of an Entity.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Entity.

versionNumber
required
integer

The version number of the Entity.

Request Body schema: application/json

Get an existing activity for a specific version of an Entity.

object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "used": [
    ]
}

Lookup an Entity ID using an alias.

Lookup an Entity ID using an alias.

Authorizations:
bearerAuth
path Parameters
alias
required
string

Alias of an Entity

Responses

Response samples

Content type
application/json
{
  • "id": "..."
}

Retrieve an entityId for a given parent ID and entity name.

Retrieve an entityId for a given parent ID and entity name. This service can also be used to lookup projectId by setting the parentId to NULL in EntityLookupRequest.

Authorizations:
bearerAuth
Request Body schema: application/json
entityName
string

The entity name

parentId
string

The parentID

Responses

Request samples

Content type
application/json
{
  • "entityName": "...",
  • "parentId": "..."
}

Response samples

Content type
application/json
{
  • "id": "..."
}

Get a page of children for a given parent ID.

Get a page of children for a given parent ID. This service can also be used to list projects by setting the parentId to NULL in EntityChildrenRequest.

Authorizations:
bearerAuth
Request Body schema: application/json
includeSumFileSizes
boolean
Default: false

When true, the sum of the files sizes (bytes) with the given parentId and types will be included. False by default

includeTotalChildCount
boolean
Default: false

When true, the total number of children with the givenparentId and types will be included. False by default

includeTypes
Array of strings (EntityType)
Items Enum: "project" "folder" "file" "table" "link" "entityview" "dockerrepo" "submissionview"

The types of children to be include. Must include at least one type.

nextPageToken
string

Optional parameter used to fetch the next page of results. When NULL, the first page will be returned. The nextPageToken is provided with the results if there is another page of results.

parentId
string

The ID of the parent. Set to null to list projects.

sortBy
string (SortBy)
Enum: "NAME" "CREATED_ON" "MODIFIED_ON"

How results should be sorted.

sortDirection
string (SortDirection)
Enum: "ASC" "DESC"

Optional sort direction. Default is the default mysql sort direction for that type.

Responses

Request samples

Content type
application/json
{
  • "includeSumFileSizes": true,
  • "includeTotalChildCount": true,
  • "includeTypes": [
    ],
  • "nextPageToken": "...",
  • "parentId": "...",
  • "sortBy": "CREATED_ON",
  • "sortDirection": "DESC"
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "page": [
    ],
  • "sumFileSizesBytes": 12345,
  • "totalChildCount": 12345
}

Get the EntityHeader for a list of references with a POST.

Get the EntityHeader for a list of references with a POST. If any item in the batch fails (e.g., with a 404) it will be EXCLUDED in the result set.

Authorizations:
bearerAuth
Request Body schema: application/json
Array of objects (Reference)

The list of references

Responses

Request samples

Content type
application/json
{
  • "references": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Gets FileEntities matching the given MD5 string which the user has read access to.

Gets at most 200 FileEntities matching the given MD5 string which the user has read access to. NOTE: Another option is to create a file view that includes MD5 values. https://docs.synapse.org/articles/views.html

Authorizations:
bearerAuth
path Parameters
md5
required
string

File MD5

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Get a batch of EntityHeader given multile Entity IDs.

Get a batch of EntityHeader given multile Entity IDs. The EntityHeader is a light weight object with basic information about an Entity includes its type.

Authorizations:
bearerAuth
query Parameters
batch
required
string

A comma separated list of Entity IDs to get EntityHeaders for.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Evaluation Services

The Evaluation API is designed to support open-access data analysis and modeling challenges in Synapse. This framework provides tools for administrators to collect and analyze data models from Synapse users created for a specific goal or purpose.

Gets Evaluations tied to a project.

Gets Evaluations tied to a project. Note: The response will contain only those Evaluations on which the caller is granted the ACCESS_TYPE.READ permission, unless specified otherwise with the accessType parameter.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the project

query Parameters
accessType
string (ACCESS_TYPE)
Enum: "CREATE" "READ" "UPDATE" "DELETE" "CHANGE_PERMISSIONS" "DOWNLOAD" "UPLOAD" "PARTICIPATE" "SUBMIT" "READ_PRIVATE_SUBMISSION" "UPDATE_SUBMISSION" "DELETE_SUBMISSION" "TEAM_MEMBERSHIP_UPDATE" "SEND_MESSAGE" "CHANGE_SETTINGS" "MODERATE"

The type of access for the user to filter for, optional and defaults to ACCESS_TYPE.READ

activeOnly
boolean
Default: false

If 'true' then return only those evaluations with rounds defined and for which the current time is in one of the rounds.

evaluationIds
string

an optional, comma-delimited list of evaluation IDs to which the response is limited

limit
integer >= 0
Default: 10

Limits the number of entities that will be fetched for this page. When null it will default to 10.

offset
integer >= 0
Default: 0

The offset index determines where this page will start from. An index of 0 is the first entity. When null it will default to 0.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 0
}

Gets a collection of Evaluations, within a given range.

Gets a collection of Evaluations, within a given range.

Note: The response will contain only those Evaluations on which the caller is

granted the ACCESS_TYPE.READ

permission, unless specified otherwise with the accessType parameter.

Authorizations:
bearerAuth
query Parameters
accessType
string
Default: "READ"
Enum: "CHANGE_PERMISSIONS" "CHANGE_SETTINGS" "CREATE" "DELETE" "DELETE_SUBMISSION" "DOWNLOAD" "MODERATE" "PARTICIPATE" "READ" "READ_PRIVATE_SUBMISSION" "SEND_MESSAGE" "SUBMIT" "TEAM_MEMBERSHIP_UPDATE" "UPDATE" "UPDATE_SUBMISSION" "UPLOAD"

The type of access for the user to filter for, optional and defaults to ACCESS_TYPE.READ

activeOnly
boolean
Default: false

If 'true' then return only those evaluations with rounds defined and for which the current time is in one of the rounds.

evaluationIds
string

an optional, comma-delimited list of evaluation IDs to which the response is limited

limit
integer [ 10 .. 100 ]
Default: 10

Maximum number of results returned

offset
integer >= 0
Default: 0

The index of the pagination offset. For a page size of 10, the first page would be at offset = 0, and the second page would be at offset = 10.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 0
}

Creates a new Evaluation.

'Creates a new Evaluation. The passed request body should contain the following fields:

  • name - Give your new Evaluation a name.
  • contentSource - The ID of the parent Entity, such as a Folder or Project.
  • status - The initial state of the Evaluation, an

    EvaluationStatus

Note: The caller must be granted the ACCESS_TYPE.CREATE on the contentSource Entity.

Authorizations:
bearerAuth
Request Body schema: application/json
contentSource
string

The Synapse ID of the Entity to which this Evaluation belongs, e.g. a reference to a Synapse project.

createdOn
string

The date on which Evaluation was created.

description
string

A text description of this Evaluation.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. The eTag changes every time an Evaluation is updated; it is used to detect when a client's copy of an Evaluation is out-of-date.

id
string

The unique immutable ID for this Evaluation.

name
string

The name of this Evaluation

ownerId
string

The ID of the Synapse user who created this Evaluation.

object (SubmissionQuota)

Maximum submissions per team/participant per submission round. If round information is omitted, then this indicates the overall submission limit per team/participant.

status
string (EvaluationStatus)
Enum: "PLANNED" "OPEN" "CLOSED" "COMPLETED"

The possible states of a Synapse Evaluation.

submissionInstructionsMessage
string

Message to display to users detailing acceptable formatting for Submissions to this Evaluation.

submissionReceiptMessage
string

Message to display to users upon successful submission to this Evaluation.

Responses

Request samples

Content type
application/json
{
  • "contentSource": "syn234444",
  • "createdOn": "12345",
  • "description": "Evaluation Queue",
  • "etag": "aaaaa",
  • "id": "12345",
  • "name": "Test Evaluation",
  • "ownerId": "22222",
  • "quota": {
    },
  • "status": "PLANNED",
  • "submissionInstructionsMessage": "Instructions",
  • "submissionReceiptMessage": "Received"
}

Response samples

Content type
application/json
{
  • "contentSource": "syn234444",
  • "createdOn": "12345",
  • "description": "Evaluation Queue",
  • "etag": "aaaaa",
  • "id": "12345",
  • "name": "Test Evaluation",
  • "ownerId": "22222",
  • "quota": {
    },
  • "status": "PLANNED",
  • "submissionInstructionsMessage": "Instructions",
  • "submissionReceiptMessage": "Received"
}

Deletes an Evaluation.

Deletes an Evaluation.

Note: The caller must be granted the ACCESS_TYPE.DELETE on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Responses

Gets an Evaluation.

Gets an Evaluation.

Note: The caller must be granted the <a

href="${org.sagebionetworks.repo.model.ACCESS_TYPE}"

ACCESS_TYPE.READ on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Responses

Response samples

Content type
application/json
{
  • "contentSource": "syn234444",
  • "createdOn": "12345",
  • "description": "Evaluation Queue",
  • "etag": "aaaaa",
  • "id": "12345",
  • "name": "Test Evaluation",
  • "ownerId": "22222",
  • "quota": {
    },
  • "status": "PLANNED",
  • "submissionInstructionsMessage": "Instructions",
  • "submissionReceiptMessage": "Received"
}

Updates an Evaluation.

'Updates an Evaluation.

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle

concurrent updates. Each time an Evaluation is updated a new etag will be

issued to the Evaluation. When an update is requested, Synapse will compare the

etag of the passed Evaluation with the current etag of the Evaluation. If the

etags do not match, then the update will be rejected with a

PRECONDITION_FAILED (412) response. When this occurs, the caller should

fetch the latest copy of the Evaluation and re-apply any changes, then re-attempt

the Evaluation update.

Note: The caller must be granted the <a

href="${org.sagebionetworks.repo.model.ACCESS_TYPE}"

ACCESS_TYPE.UPDATE on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Request Body schema: application/json
contentSource
string

The Synapse ID of the Entity to which this Evaluation belongs, e.g. a reference to a Synapse project.

createdOn
string

The date on which Evaluation was created.

description
string

A text description of this Evaluation.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. The eTag changes every time an Evaluation is updated; it is used to detect when a client's copy of an Evaluation is out-of-date.

id
string

The unique immutable ID for this Evaluation.

name
string

The name of this Evaluation

ownerId
string

The ID of the Synapse user who created this Evaluation.

object (SubmissionQuota)

Maximum submissions per team/participant per submission round. If round information is omitted, then this indicates the overall submission limit per team/participant.

status
string (EvaluationStatus)
Enum: "PLANNED" "OPEN" "CLOSED" "COMPLETED"

The possible states of a Synapse Evaluation.

submissionInstructionsMessage
string

Message to display to users detailing acceptable formatting for Submissions to this Evaluation.

submissionReceiptMessage
string

Message to display to users upon successful submission to this Evaluation.

Responses

Request samples

Content type
application/json
{
  • "contentSource": "syn234444",
  • "createdOn": "12345",
  • "description": "Evaluation Queue",
  • "etag": "aaaaa",
  • "id": "12345",
  • "name": "Test Evaluation",
  • "ownerId": "22222",
  • "quota": {
    },
  • "status": "PLANNED",
  • "submissionInstructionsMessage": "Instructions",
  • "submissionReceiptMessage": "Received"
}

Response samples

Content type
application/json
{
  • "contentSource": "syn234444",
  • "createdOn": "12345",
  • "description": "Evaluation Queue",
  • "etag": "aaaaa",
  • "id": "12345",
  • "name": "Test Evaluation",
  • "ownerId": "22222",
  • "quota": {
    },
  • "status": "PLANNED",
  • "submissionInstructionsMessage": "Instructions",
  • "submissionReceiptMessage": "Received"
}

Determines whether a specified Synapse user has a certain access type on evaluation.

Determines whether the logged in user has a certain ACCESS_TYPE on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

query Parameters
accessType
required
string

Synapse access type

Responses

Response samples

Content type
application/json
{
  • "result": true
}

This method is deprecated and should be removed from future versions of the API. Deprecated

This method is deprecated and should be removed from future versions of the API.

Deletes the ACL (access control list) of the specified evaluation. The user should have the proper permissions to delete the ACL.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Responses

Gets the access control list (ACL) governing the given evaluation.

Gets the access control list (ACL) governing the given evaluation. The user should have the proper permissions to read the ACL.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Create Evaluation Round Deprecated

Create Evaluation Round

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Request Body schema: application/json
etag
string

Synapse etag

evaluationId
string

The unique immutable ID for this Evaluation.

id
string

Evaluation round Id

Array of objects (EvaluationRoundLimit)

List of round limits

roundEnd
string

End of round

roundStart
string

Start of round

Responses

Request samples

Content type
application/json
{
  • "etag": "...",
  • "evaluationId": "...",
  • "id": "...",
  • "limits": [
    ],
  • "roundEnd": "12345",
  • "roundStart": "12345"
}

Response samples

Content type
application/json
{
  • "etag": "...",
  • "evaluationId": "...",
  • "id": "...",
  • "limits": [
    ],
  • "roundEnd": "12345",
  • "roundStart": "12345"
}

Delete Evaluation Round Deprecated

Delete Evaluation Round

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

roundId
required
string

The ID of the evaluation round

Responses

Get Evaluation Round Deprecated

Get Evaluation Round

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

roundId
required
string

The ID of the evaluation round

Responses

Response samples

Content type
application/json
{
  • "etag": "...",
  • "evaluationId": "...",
  • "id": "...",
  • "limits": [
    ],
  • "roundEnd": "12345",
  • "roundStart": "12345"
}

Update Evaluation Round Deprecated

Update Evaluation Round

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

roundId
required
string

The ID of the evaluation round

Request Body schema: application/json
etag
string

Synapse etag

evaluationId
string

The unique immutable ID for this Evaluation.

id
string

Evaluation round Id

Array of objects (EvaluationRoundLimit)

List of round limits

roundEnd
string

End of round

roundStart
string

Start of round

Responses

Request samples

Content type
application/json
{
  • "etag": "...",
  • "evaluationId": "...",
  • "id": "...",
  • "limits": [
    ],
  • "roundEnd": "12345",
  • "roundStart": "12345"
}

Response samples

Content type
application/json
{
  • "etag": "...",
  • "evaluationId": "...",
  • "id": "...",
  • "limits": [
    ],
  • "roundEnd": "12345",
  • "roundStart": "12345"
}

Get all rounds of an Evaluation Deprecated

Get all rounds of an Evaluation

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Request Body schema: application/json
nextPageToken
string

The token required to be sent with the subsequent batch.

Responses

Request samples

Content type
application/json
{
  • "nextPageToken": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "page": [
    ]
}

Update multiple SubmissionStatuses.

Update multiple SubmissionStatuses. The maximum batch size is 500. To allow upload of more than this maximum, the system supports uploading of a series of batches. Synapse employs optimistic concurrency on the series in the form of a batch token. Each request (except the first) must include the ''batch token'' returned in the response to the previous batch. If another client begins batch upload simultaneously, a PRECONDITION_FAILED (412) response will be generated and upload must restart from the first batch. After the final batch is uploaded, the data for the Evaluation queue will be mirrored to the tables which support querying. Therefore uploaded data will not appear in Evaluation queries until after the final batch is successfully uploaded. It is the client''s responsibility to note in each batch request (1) whether it is the first batch in the series and (2) whether it is the last batch. (For a single batch both are set to ''true''.)

Failure to use the flags correctly risks corrupted data (due to simultaneous, conflicting uploads by multiple clients) or data not appearing in query results.

Note: The caller must be granted the ACCESS_TYPE.UPDATE_SUBMISSION on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Request Body schema: application/json
batchToken
string

A token required to accept a batch submission for all but the first batch.

isFirstBatch
boolean

true if and only if this is the first batch to upload

isLastBatch
boolean

true if and only if this is the last batch to upload

Array of objects (SubmissionStatus)

A collection of Submission Statuses

Responses

Request samples

Content type
application/json
{
  • "batchToken": "...",
  • "isFirstBatch": true,
  • "isLastBatch": true,
  • "statuses": [
    ]
}

Response samples

Content type
application/json
{
  • "nextUploadToken": "..."
}

Gets the requesting user's Submissions to a specified Evaluation.

Gets the requesting user's Submissions to a specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Limits the number of entities that will be fetched for this page. When null it will default to 10.

offset
integer >= 0
Default: 0

The offset index determines where this page will start from. An index of 0 is the first entity. When null it will default to 0.'

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Gets a collection of Submissions to a specified Evaluation.

'Gets a collection of Submissions to a specified Evaluation.

Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Limits the number of entities that will be fetched for this page. When null it will default to 10, max value 100.

offset
integer
Default: 0

The offset index determines where this page will start from. An index of 0 is the first entity. When null it will default to 0.

status
string

Status of submission.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Gets the requesting users bundled Submissions and SubmissionStatuses to a specified Evaluation.'

Gets the requesting user's bundled Submissions and SubmissionStatuses to a specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Limits the number of entities that will be fetched for this page. When null it will default to 10.'

offset
integer
Default: 0

The offset index determines where this page will start from. An index of 0 is the first entity. When null it will default to 0.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Gets a collection of bundled Submissions and SubmissionStatuses to a given Evaluation.

Gets a collection of bundled Submissions and SubmissionStatuses to a given Evaluation.

Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Limits the number of entities that will be fetched for this page. When null it will default to 10.'

offset
integer
Default: 0

The offset index determines where this page will start from. An index of 0 is the first entity. When null it will default to 0.

status
string

Submission Status

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Gets the number of Submissions to a specified Evaluation.

Gets the number of Submissions to a specified Evaluation. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

Responses

Response samples

Content type
application/json
0

Gets a collection of SubmissionStatuses to a specified Evaluation.

'Gets a collection of SubmissionStatuses to a specified Evaluation.

Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation. Furthermore, the caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION to see all data marked as "private" in the SubmissionStatuses.

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

Limits the number of entities that will be fetched for this page. When null it will default to 10.'

offset
integer
Default: 0

The offset index determines where this page will start from. An index of 0 is the first entity. When null it will default to 0.

status
string

Submission status

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Find out whether a Team and its members are eligible to submit to a given Evaluation queue (at the current time).'

Find out whether a Team and its members are eligible to submit to a given Evaluation queue (at the current time). The request must include an Evaluation ID and a Team ID. The 'eligibilityStateHash' field of the returned object is a required parameter of the subsequent Team Submission request made for the given Evaluation and Team. (See: POST/evaluation/submission)'

Authorizations:
bearerAuth
path Parameters
evalId
required
string

The ID of the specified Evaluation.

id
required
string

The ID of a Team.

Responses

Response samples

Content type
application/json
{
  • "eligibilityStateHash": 12345,
  • "evaluationId": "...",
  • "membersEligibility": [
    ],
  • "teamEligibility": {
    },
  • "teamId": "..."
}

Updates the supplied access control list (ACL) for an evaluation.

Updates the supplied access control list (ACL) for an evaluation. The ACL to be updated should have the ID of the evaluation. The user should have the proper permissions in order to update the ACL.

Authorizations:
bearerAuth
Request Body schema: application/json

The ACL being updated.

createdBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

creationDate
string

Created Date

etag
string

Synapse etag value

id
string

The entity id

modifiedBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

modifiedOn
string

UNUSED -- maintained only for backwards compatibility with archived objects

Array of objects (ResourceAccess)

The list of principals who can access the data with the allowed types of access for each.

Responses

Request samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Gets a collection of Evaluations in which the user has SUBMIT permission, within a given range.

Gets a collection of Evaluations in which the user has SUBMIT permission, within a given range.

Note: The response will contain only those Evaluations on which the caller must is granted the ACCESS_TYPE.SUBMIT permission.

Authorizations:
bearerAuth
query Parameters
activeOnly
boolean
Default: false

Retrieve active only evaluation queues

evaluationIds
string

an optional, comma-delimited list of evaluation IDs to which the response is limited

limit
integer [ 10 .. 100 ]
Default: 10

Limits the number of entities that will be fetched for this page. When null it will default to 10.'

offset
integer
Default: 0

The offset index determines where this page will start from. An index of 0 is the first entity. When null it will default to 0.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 0
}

Finds an Evaluation by name.

Finds an Evaluation by name.

Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
name
required
string

The name of the desired Evaluation.

Responses

Response samples

Content type
application/json
{
  • "contentSource": "syn234444",
  • "createdOn": "12345",
  • "description": "Evaluation Queue",
  • "etag": "aaaaa",
  • "id": "12345",
  • "name": "Test Evaluation",
  • "ownerId": "22222",
  • "quota": {
    },
  • "status": "PLANNED",
  • "submissionInstructionsMessage": "Instructions",
  • "submissionReceiptMessage": "Received"
}

Creates a Submission and sends a submission notification email to the submitter's team members.

Creates a Submission and sends a submission notification email to the submitter's team members.

The passed request body should contain the following fields:

  • evaluationId - The ID of the Evaluation to which this Submission belongs.
  • entityId - The ID of the Entity being submitted.
  • versionNumber - The specific version of the Entity being submitted.

A Submission must be either a Team or an Individual submission. A Team submission must include a Team ID in the teamId field and the request must include a submissionEligibilityHash request parameter. A Team submission may also include a list of submission contributors. (The submitter is taken to be a contributor and need not be included in the list.) An individual submission must have a null teamId, a null or empty contributor list, and no submissionEligibilityHash parameter.

Note: The caller must be granted the ACCESS_TYPE.SUBMIT.

This call also creates an associated SubmissionStatus, initialized with a SubmissionStatusEnum value of RECEIVED.

Authorizations:
bearerAuth
query Parameters
challengeEndpoint
string

The portal endpoint prefix to the an entity/challenge page. The entity ID of the challenge project is appended to create the complete URL. In normal operation, this parameter should be omitted.'

etag
string

The current eTag of the Entity being submitted

notificationUnsubscribeEndpoint
string

The portal endpoint prefix for one-click email unsubscription. A signed, serialized token is appended to create the complete URL: NotificationSettingsSignedToken. In normal operation, this parameter should be omitted.'

submissionEligibilityHash
string

The hash provided by the TeamSubmissionEligibility object.

Request Body schema: application/json
Array of objects (SubmissionContributor)

User ids of the submitter and (if a team submission) the team members involved in creating the submission.

createdOn
string

The date on which Submission was created.

dockerDigest
string

For Docker repositories, the digest from the commit. Null for other entity types.

dockerRepositoryName
string

For Docker repositories, the name of the submitted repository. Null for other entity types.

entityBundleJSON
string

The Bundled Entity and Annotations JSON at the time of submission.

entityId
string

The Synapse ID of the Entity in this Submission.

evaluationId
string

The Synapse ID of the Evaluation this Submission is for.

evaluationRoundId
string

The Synapse ID of the EvaluationRound to which this was submitted. DO NOT specify a value for this. It will be filled in automatically upon creation of the Submission if the Evaluation is configured with an EvaluationRound.

id
string

The unique, immutable Synapse ID of this Submission.

name
string

The title of this Submission.

submitterAlias
string

The alias for the user or team creating the submission.

teamId
string

optional Team which collaborated on the submission

userId
string

The Synapse ID of the user who created this Submission.

versionNumber
integer

The submitted version number of the Entity.

Responses

Request samples

Content type
application/json
{
  • "contributors": [
    ],
  • "createdOn": "...",
  • "dockerDigest": "...",
  • "dockerRepositoryName": "...",
  • "entityBundleJSON": "...",
  • "entityId": "...",
  • "evaluationId": "...",
  • "evaluationRoundId": "...",
  • "id": "...",
  • "name": "...",
  • "submitterAlias": "...",
  • "teamId": "...",
  • "userId": "...",
  • "versionNumber": 12345
}

Response samples

Content type
application/json
{
  • "contributors": [
    ],
  • "createdOn": "...",
  • "dockerDigest": "...",
  • "dockerRepositoryName": "...",
  • "entityBundleJSON": "...",
  • "entityId": "...",
  • "evaluationId": "...",
  • "evaluationRoundId": "...",
  • "id": "...",
  • "name": "...",
  • "submitterAlias": "...",
  • "teamId": "...",
  • "userId": "...",
  • "versionNumber": 12345
}

Deletes a Submission and its accompanying SubmissionStatus.

Deletes a Submission and its accompanying SubmissionStatus.

This service is intended to only be used by ChallengesInfrastructure service account.

Note: The caller must be granted the ACCESS_TYPE.DELETE_SUBMISSION on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
subId
required
string

The ID of the Submission

Responses

Gets a Submission.

Gets a Submission.

Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
subId
required
string

The ID of the Submission

Responses

Response samples

Content type
application/json
{
  • "contributors": [
    ],
  • "createdOn": "...",
  • "dockerDigest": "...",
  • "dockerRepositoryName": "...",
  • "entityBundleJSON": "...",
  • "entityId": "...",
  • "evaluationId": "...",
  • "evaluationRoundId": "...",
  • "id": "...",
  • "name": "...",
  • "submitterAlias": "...",
  • "teamId": "...",
  • "userId": "...",
  • "versionNumber": 12345
}

User requests to cancel their submission.

User requests to cancel their submission. Only the user who submitted a submission can make this request.

Authorizations:
bearerAuth
path Parameters
subId
required
string

The ID of the Submission

Responses

Gets a pre-signed URL to access a requested File contained within a specified Submission.

Gets a pre-signed URL to access a requested File contained within a specified Submission. Note: The caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION on the specified Evaluation.

Authorizations:
bearerAuth
path Parameters
fileHandleId
required
string

the ID of the requested FileHandle contained in the Submission.

subId
required
string

The ID of the Submission

query Parameters
redirect
boolean

To redirect

Responses

Response samples

Content type
application/json
"string"

Gets the SubmissionStatus object associated with a specified Submission.

Gets the SubmissionStatus object associated with a specified Submission.

Note: The caller must be granted the ACCESS_TYPE.READ on the specified Evaluation. Furthermore, the caller must be granted the ACCESS_TYPE.READ_PRIVATE_SUBMISSION to see all data marked as "private" in the SubmissionStatus.

Service Limits

resource limit
The maximum frequency this method can be called 1 calls per second

Authorizations:
bearerAuth
path Parameters
subId
required
string

The ID of the Submission

Responses

Response samples

Content type
application/json
{
  • "annotations": {
    },
  • "canCancel": true,
  • "cancelRequested": true,
  • "entityId": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedOn": "12345",
  • "status": "ACCEPTED",
  • "statusVersion": 12345,
  • "submissionAnnotations": {
    },
  • "versionNumber": 12345
}

Updates a SubmissionStatus object.

Updates a SubmissionStatus object.

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Each time an SubmissionStatus is updated a new etag will be issued to the SubmissionStatus. When an update is requested, Synapse will compare the etag of the passed SubmissionStatus with the current etag of the SubmissionStatus. If the etags do not match, then the update will be rejected with a PRECONDITION_FAILED (412) response. When this occurs, the caller should fetch the latest copy of the SubmissionStatus and re-apply any changes, then re-attempt the SubmissionStatus update.

Note: The caller must be granted the ACCESS_TYPE.UPDATE_SUBMISSION on the specified Evaluation.

Service Limits

resource limit
The maximum frequency this method can be called 1 calls per second

Authorizations:
bearerAuth
path Parameters
subId
required
string

The ID of the Submission

Request Body schema: application/json
object (Annotations)

Primary container object for Annotations on a Synapse object

canCancel
boolean

Can this submission be cancelled? By default, this will be set to False. Users can read this value. Only the queue's scoring application can change this value.

cancelRequested
boolean

Has user requested to cancel this submission? By default, this will be set to False. Submission owner can read and request to change this value.

entityId
string

The Synapse ID of the Entity in this Submission.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. The eTag changes every time an SubmissionStatus is updated; it is used to detect when a client's copy of an SubmissionStatus is out-of-date.

id
string

The unique, immutable Synapse ID of the Submission.

modifiedOn
string

The date on which this SubmissionStatus was last modified.

status
string (SubmissionStatusEnum)
Enum: "OPEN" "CLOSED" "SCORED" "INVALID" "VALIDATED" "EVALUATION_IN_PROGRESS" "RECEIVED" "REJECTED" "ACCEPTED"

The possible states of a Synapse Submission.

statusVersion
number

A version of the status, auto-generated and auto-incremented by the system and read-only to the client.

object (Annotations)

Annotations are additional key-value pair metadata that are associated with an object.

versionNumber
integer

The version number of the Entity in this Submission.

Responses

Request samples

Content type
application/json
{
  • "annotations": {
    },
  • "canCancel": true,
  • "cancelRequested": true,
  • "entityId": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedOn": "12345",
  • "status": "ACCEPTED",
  • "statusVersion": 12345,
  • "submissionAnnotations": {
    },
  • "versionNumber": 12345
}

Response samples

Content type
application/json
{
  • "annotations": {
    },
  • "canCancel": true,
  • "cancelRequested": true,
  • "entityId": "...",
  • "etag": "...",
  • "id": "...",
  • "modifiedOn": "12345",
  • "status": "ACCEPTED",
  • "statusVersion": 12345,
  • "submissionAnnotations": {
    },
  • "versionNumber": 12345
}

Form Services

Collection of APIs from managing and submitting form data.

Create a new FormData object.

Create a new FormData object. The caller will own the resulting object and will have access to read, update, and delete the FormData object.

Note: The caller must have the SUBMIT permission on the FormGrup to reate/update/submit FormData.

Authorizations:
bearerAuth
query Parameters
groupId
required
string

The identifier of the group that manages this data.

Request Body schema: application/json
fileHandleId
string

The fileHandleId for the data of the form.

name
string [ 3 .. 256 ] characters

The name of the form. Required for FormData create. Optional for FormData update. Between 3 and 256 characters'

Responses

Request samples

Content type
application/json
{
  • "fileHandleId": "...",
  • "name": "..."
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "dataFileHandleId": "...",
  • "etag": "...",
  • "formDataId": "...",
  • "groupId": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "submissionStatus": {
    }
}

Delete a FormData object.

Delete an existing FormData object. The caller must be the creator of the FormData object.

Note: Cannot delete a FormData object once it has been submitted and caller must have the SUBMIT permission on the identified group to update the group's ACL.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the FormData.

Responses

Response samples

Content type
application/json
"string"

Update a FormData object.

Update an existing FormData object. The caller must be the creator of the FormData object. Once a FormData object has been submitted, it cannot be updated until it has been processed. If the submission is accepted it becomes immutable. Rejected submission are editable. Updating a rejected submission will change its status back to waiting_for_submission.

Note: The caller must have the SUBMIT permission on the FormGrup to create/update/submit FormData.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the FormData.

Request Body schema: application/json
fileHandleId
string

The fileHandleId for the data of the form.

name
string [ 3 .. 256 ] characters

The name of the form. Required for FormData create. Optional for FormData update. Between 3 and 256 characters'

Responses

Request samples

Content type
application/json
{
  • "fileHandleId": "...",
  • "name": "..."
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "dataFileHandleId": "...",
  • "etag": "...",
  • "formDataId": "...",
  • "groupId": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "submissionStatus": {
    }
}

Called by the form reviewing service to accept a submitted data.

Called by the form reviewing service to accept a submitted data.

Note: The caller must have the READ_PRIVATE_SUBMISSION permission on the identified group to update the group's ACL.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the FormData.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "dataFileHandleId": "...",
  • "etag": "...",
  • "formDataId": "...",
  • "groupId": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "submissionStatus": {
    }
}

Called by the form reviewing service to reject a submitted data.

Called by the form reviewing service to reject a submitted data.

Note: The caller must have the READ_PRIVATE_SUBMISSION permission on the identified group to update the group's ACL.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the FormData.

Request Body schema: application/json
reason
string <= 500 characters

The reason for the rejection. Limit 500 characters or less.

Responses

Request samples

Content type
application/json
{
  • "reason": "..."
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "dataFileHandleId": "...",
  • "etag": "...",
  • "formDataId": "...",
  • "groupId": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "submissionStatus": {
    }
}

Submit the identified FormData from review.

Submit the identified FormData from review.

Note: The caller must have the SUBMIT permission on the identified group to update the group's ACL.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the FormData.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "dataFileHandleId": "...",
  • "etag": "...",
  • "formDataId": "...",
  • "groupId": "...",
  • "modifiedOn": "...",
  • "name": "...",
  • "submissionStatus": {
    }
}

List FormData objects and their associated status.

List FormData objects and their associated status that match the filters of the provided request that are owned by the caller. Note: Only objects owned by the caller will be returned.

Authorizations:
bearerAuth
Request Body schema: application/json
filterByState
Array of strings (StateEnum)
Items Enum: "WAITING_FOR_SUBMISSION" "SUBMITTED_WAITING_FOR_REVIEW" "ACCEPTED" "REJECTED"

Only return results with a state that matches elements from this set. Required. Must include at least one element.

groupId
string

The group identifier. Required.

nextPageToken
string

The results are automatically paginated. To get the next page, forward the nextPageToken returned from the last request.

Responses

Request samples

Content type
application/json
{
  • "filterByState": [
    ],
  • "groupId": "...",
  • "nextPageToken": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "page": [
    ]
}

List FormData objects and their associated status.

List FormData objects and their associated status that match the filters of the provided request for the entire group. This is used by service accounts to review submissions. Filtering by WAITING_FOR_SUBMISSION is not allowed for this call.

Note: The caller must have the READ_PRIVATE_SUBMISSION permission on the identified group to update the group's ACL.

Authorizations:
bearerAuth
Request Body schema: application/json
filterByState
Array of strings (StateEnum)
Items Enum: "WAITING_FOR_SUBMISSION" "SUBMITTED_WAITING_FOR_REVIEW" "ACCEPTED" "REJECTED"

Only return results with a state that matches elements from this set. Required. Must include at least one element.

groupId
string

The group identifier. Required.

nextPageToken
string

The results are automatically paginated. To get the next page, forward the nextPageToken returned from the last request.

Responses

Request samples

Content type
application/json
{
  • "filterByState": [
    ],
  • "groupId": "...",
  • "nextPageToken": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "page": [
    ]
}

Create a FormGroup with the provided name.

Create a FormGroup with the provided name. This method is idempotent. If a group with the provided name already exists and the caller has READ permission the existing FormGroup will be returned.

The created FormGroup will have an Access Control List (ACL) with the creator listed as an administrator.

Authorizations:
bearerAuth
query Parameters
name
required
string [ 3 .. 256 ] characters

A globally unique name for the group. Required. Between 3 and 256 characters.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "groupId": "...",
  • "name": "..."
}

Get a FormGroup with the provided ID.

Get a FormGroup with the provided ID.

Note: The caller must have the READ permission on the identified group.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID to the FormGroup.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "groupId": "...",
  • "name": "..."
}

Get the ACL for a FormGroup

Get the Access Control List (ACL) for a FormGroup.

Note: The caller must have READ permission on the identified group.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the FormGroup.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Update the ACL for a FormGroup.

Update the Access Control List (ACL) for a FormGroup.

The following define the permissions in this context:

  • READ - Grants read access to the group. READ does not grant access to FormData of the group.
  • CHANGE_PERMISSIONS - Grants access to update the group's ACL.
  • SUBMIT - Grants access to both create and submit FormData to the group.
  • READ_PRIVATE_SUBMISSION - Grants administrator's access to the submitted FormData, including both FormData reads and status updates. This permission should be reserved for the service account that evaluates submissions.

Users automatically have read/update access to FormData that they create.

Note: The caller must have the CHANGE_PERMISSIONS permission on the identified group to update the group's ACL.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the FormGroup.

Request Body schema: application/json
createdBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

creationDate
string

Created Date

etag
string

Synapse etag value

id
string

The entity id

modifiedBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

modifiedOn
string

UNUSED -- maintained only for backwards compatibility with archived objects

Array of objects (ResourceAccess)

The list of principals who can access the data with the allowed types of access for each.

Responses

Request samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Json Schema Services

This set of services provide project designers with tools to define their own schemas to control and validate metadata applied to Projects, Folders, and Files.

List all JSON schemas for an Organization.

List all JSON schemas for an Organization. Each call will return a single page of schemas. Forward the provided nextPageToken to get the next page.

Authorizations:
bearerAuth
Request Body schema: application/json
nextPageToken
string

Forward the returned 'nextPageToken' to get the next page of results.

organizationName
string

The name of the Organization to list schemas for.

Responses

Request samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "organizationName": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "page": [
    ]
}

Lookup an Organization by name.

Lookup an Organization by name.

Authorizations:
bearerAuth
query Parameters
name
required
string

The name of the Organization to lookup.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "id": "...",
  • "name": "..."
}

Create a new Organization.

Create a new Organization by providing a unique organization name. The new Organization will have an auto-generated AcessControlList (ACL) granting the caller all relevant permission on the newly created Organization.

Authorizations:
bearerAuth
Request Body schema: application/json
organizationName
string [ 6 .. 250 ] characters ^((?!sagebionetworks)[a-zA-Z0-9.])*$

An organization name must be one or more alphanumeric strings each separated by a dot [ ('.')]. An alphanumeric string must start with a letter followed by one or more letters or digits a-z. Names are case insensitive. Names cannot contain the reserved word 'sagebionetworks'

Responses

Request samples

Content type
application/json
{
  • "organizationName": "testing0983"
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "id": "...",
  • "name": "..."
}

Delete the identified Organization.

Delete the identified Organization. All schemas defined within the Organization''s name-space must first be deleted before an Organization can be deleted.

Note: The caller must be granted the DELETE permission on the Organization.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Organization.

Responses

Response samples

Content type
application/json
"string"

Get the ACL associated of an Organization.

Get the AcessControlList (ACL) associated with the identified Organization.

Note: The caller must be granted the READ permission to get an Organization's ACL.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Organization.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Update the AccessControlList (ACL) for the identified Organization.

Update the AccessControlList (ACL) for the identified Organization.

Note: The caller must be granted the CHANGE_PERMISSIONS permission to update an Organization's ACL.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Organization.

Request Body schema: application/json
createdBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

creationDate
string

Created Date

etag
string

Synapse etag value

id
string

The entity id

modifiedBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

modifiedOn
string

UNUSED -- maintained only for backwards compatibility with archived objects

Array of objects (ResourceAccess)

The list of principals who can access the data with the allowed types of access for each.

Responses

Request samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

List all organizations.

List all organizations. Each call will return a single page of Organizations. Forward the provided nextPageToken to get the next page.

Authorizations:
bearerAuth
Request Body schema: application/json
nextPageToken
string

Forward the returned 'nextPageToken' to get the next page of results.

Responses

Request samples

Content type
application/json
{
  • "nextPageToken": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "page": [
    ]
}

Get the results of an asynchronous job that was started to create a new JSON schema.

Get the results of an asynchronous job that was started to create a new JSON schema.

Note: If the job has not completed, this method will return a status code of 202 (ACCEPTED) and the response body will be a AsynchronousJobStatus object.

Authorizations:
bearerAuth
path Parameters
asyncToken
required
string

Forward the token returned when the job was started.

Responses

Response samples

Content type
application/json
{
  • "concreteType": "string",
  • "newVersionInfo": {
    },
  • "validationSchema": {
    }
}

Start an asynchronous job to create a new JSON schema.

Start an asynchronous job to create a new JSON schema. A JSON schema must include an $id that is a relative URL of that schema. The pseudo-BNF syntax for a valid $id is as follows:

< $id > ::= < organization name > "-" < schema name > [ "-" < semantic version > ]

< organization name > ::= < dot separated alpha numeric >

< schema name > ::= < dot separated alpha numeric >

< semantic version > ::= See: https://semver.org/

< dot separated alpha numeric > :: = < alpha numeric > ( "." < alpha numeric > )*

< alpha numeric > ::= < letter > ( < identifier > )*

< letter > ::= [a-zA-Z]

< identifier > ::= < letter > | < digit >

< digit > :: = [0-9]

Take the following example, if organizationName="my.organization", schemaName="foo.Bar.json", and semanticVersion="0.1.2", then $id="my.organization-foo.Bar.json-0.1.2". Note: The semantic version is optional. When provide the semantic version is a label for a specific version that allows other schemas to reference it by its version. When a semantic version is include, that version of the schema is immutable. This means if a semantic version is included in a registered schema's $id, all $refs within the schema must also include a semantic version.

All $ref within a JSON schema must either be references to "definitions" within the schema or references other registered JSON schemas. References to non-registered schemas is not currently supported. To reference a registered schema $ref should equal the $id of the referenced schema. To reference the example schema from above use $ref="my.organization-foo.Bar.json-0.1.2".

Note: The semantic version of a referenced schema is optional. When the semantic version is excluded in a $ref the reference is assumed to reference the latest version of the schema. So $ref="my.organization-foo.Bar.json" would be a reference to the latest version of that schema. While $ref="my.organization-foo.Bar.json-0.1.2" would be a reference to the version 0.1.2

To monitor the progress of the job and to get the final results use: GET /schema/type/create/async/get/{asyncToken}

Note: The caller must be granted the CREATE permission on the Organization in the schema's $id.

Authorizations:
bearerAuth
Request Body schema: application/json
concreteType
string

Concrete Type

dryRun
boolean

When true, an attempt will be made to create the schema normally, but the resulting schema will not be retained. This can be used to validate a schema without actually registering it. The default value is false.

object (JsonSchema)

The JSON schema is defined by: json-schema.org, specifically draft-07. Only features listed here are currently supported.

Responses

Request samples

Content type
application/json
{
  • "concreteType": "string",
  • "dryRun": true,
  • "schema": {
    }
}

Response samples

Content type
application/json
{
  • "token": "..."
}

deleteJsonSchema

Delete the given schema using its $id. If the $id excludes a semantic version, all versions of the schema will be deleted. If the $id includes a semantic version then just that version will be deleted. Caution: This operation cannot be undone.

Note: The caller must be granted the DELETE permission on the schema's organization.

Authorizations:
bearerAuth
path Parameters
id
required
string

The $id of the schema to delete.

Responses

Get a registered JSON schema using its $id.

Get a registered JSON schema using its $id.

Authorizations:
bearerAuth
path Parameters
id
required
string

The $id of the schema to delete.

Responses

Response samples

Content type
application/json
{
  • "$id": "string",
  • "$ref": "string",
  • "$schema": "string",
  • "_const": "string",
  • "_else": { },
  • "_enum": [
    ],
  • "_if": { },
  • "allOf": [
    ],
  • "anyOf": [
    ],
  • "definitions": {
    },
  • "description": "string",
  • "format": "string",
  • "items": { },
  • "maxLength": 0,
  • "minLength": 0,
  • "oneOf": [
    ],
  • "pattern": "string",
  • "properties": {
    },
  • "required": [
    ],
  • "source": "string",
  • "then": { },
  • "title": "string",
  • "type": "null"
}

Get the results of an asynchronous job that was started to compile a 'validation' schema for a JSON schema.

Get the results of an asynchronous job that was started to compile a 'validation' schema for a JSON schema.

Note: If the job has not completed, this method will return a status code of 202 (ACCEPTED) and the response body will be a AsynchronousJobStatus object.

Authorizations:
bearerAuth
path Parameters
asyncToken
required
string

Forward the token returned when the job was started.

Responses

Response samples

Content type
application/json
{
  • "concreteType": "string",
  • "validationSchema": {
    }
}

Start validating JSON schema

To use a JSON schema for validation, the JSON schema plus all of its dependency schemas must be provided to a JSON schema validator. The 'validation' schema is simply a JSON schema with all of its dependencies added to the 'definitions' section of the schema, making the schema self-contained.

Use this call to start an asynchronous job that will compile the 'validation' schema for a given JSON schema $id.

To monitor the progress of the job and to get the final results use: GET /schema/type/validation/async/get/{asyncToken}

Authorizations:
bearerAuth
Request Body schema: application/json
$id
string

The $id of the JSON schema to get the validation schema for.

concreteType
string

Concrete Type

Responses

Request samples

Content type
application/json
{
  • "$id": "...",
  • "concreteType": "..."
}

Response samples

Content type
application/json
{
  • "token": "..."
}

List the version information for each version of a given schema.

List the version information for each version of a given schema. Each call will return a single page of results. Forward the provide nextPageToken to get the next page of results.

Authorizations:
bearerAuth
Request Body schema: application/json
nextPageToken
string

Forward the returned 'nextPageToken' to get the next page of results.

organizationName
string

The name of the Organization.

schemaName
string

The name of the JsonSchema to list versions to list schemas for.

Responses

Request samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "organizationName": "...",
  • "schemaName": "..."
}

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "page": [
    ]
}

Membership Invitation Services

The Membership Invitation Services create, retrieve and delete membership invitations.

Create membership invitation

Create a membership invitation and send an email notification to the invitee. The team must be specified.

Also, either an inviteeId or an inviteeEmail must be specified. Optionally, the creator may include an invitation message and/or expiration date for the invitation. If no expiration date is specified then the invitation never expires.

Note: The client must be an team manager of the specified Team to make this request.

Authorizations:
bearerAuth
query Parameters
acceptInvitationEndpoint
string

The portal endpoint prefix for one-click acceptance of the membership invitation.

A signed, serialized token is appended to create the complete URL: JoinTeamSignedToken if an inviteeId is specified, or MembershipInvtnSignedToken if an inviteeEmail is specified. In normal operation, this parameter should be omitted.

notificationUnsubscribeEndpoint
string
Default: "https://www.synapse.org/#!SignedToken:Settings/"

The portal endpoint prefix for one-click email unsubscription. A signed, serialized token is appended to create the complete URL: NotificationSettingsSignedToken

In normal operation, this parameter should be omitted.

Request Body schema: application/json
createdBy
string

The ID of the user that created this MembershipInvitation.

createdOn
string

The date this MembershipInvitation was created.

expiresOn
string

The date this invitation expires (optional).

id
string

The id of the MembershipInvitation.

inviteeEmail
string

The email address of the user being invited to join the Team.

inviteeId
string

The principal ID of the user being invited to join the Team.

message
string

The invitation message (optional).

teamId
string

The id of the Team which the user is invited to join.

Responses

Request samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "id": "...",
  • "inviteeEmail": "...",
  • "inviteeId": "...",
  • "message": "...",
  • "teamId": "..."
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "id": "...",
  • "inviteeEmail": "...",
  • "inviteeId": "...",
  • "message": "...",
  • "teamId": "..."
}

Delete an invitation

Delete an invitation

Note: The client must be an administrator of the Team referenced by the invitation or the invitee to make this request.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the invitation.

Responses

Retrieve an invitation by ID.

Retrieve an invitation by ID

Note: The client must be an administrator of the Team referenced by the invitation or the invitee to make this request.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the invitation.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "id": "...",
  • "inviteeEmail": "...",
  • "inviteeId": "...",
  • "message": "...",
  • "teamId": "..."
}

Retrieve an invitation by ID using a MembershipInvtnSignedToken.

Retrieve an invitation by ID using a MembershipInvtnSignedToken for authorization

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the invitation.

Request Body schema: application/json
concreteType
string

Concrete Type

createdOn
string

The date-time the token was generated.

expiresOn
string

The date-time when this token expires.

hmac
string

The hash message authentication code for the message.

membershipInvitationId
string

The ID of the membership invitation.

version
integer

The version of the key used to generate the HMAC.

Responses

Request samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "hmac": "...",
  • "membershipInvitationId": "...",
  • "version": 12345
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "id": "...",
  • "inviteeEmail": "...",
  • "inviteeId": "...",
  • "message": "...",
  • "teamId": "..."
}

Set the inviteeId of a MembershipInvitation.

Set the inviteeId of a MembershipInvitation.

A valid InviteeVerificationSignedToken must have an inviteeId equal to the id of the authenticated user and a membershipInvitationId equal to the id in the URI. This call will only succeed if the indicated MembershipInvitation has a null inviteeId and a non null inviteeEmail.

See https://sagebionetworks.jira.com/wiki/spaces/PLFM/pages/143628166/Invite+a+new+user+to+join+a+team for more information.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the invitation.

Request Body schema: application/json
concreteType
string

Concrete Type

createdOn
string

The date-time the token was generated.

expiresOn
string

The date-time when this token expires.

hmac
string

The hash message authentication code for the message.

inviteeId
string

The ID of the invitee.

membershipInvitationId
string

The ID of the MembershipInvitation to update.

version
integer

The version of the key used to generate the HMAC.

Responses

Request samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "hmac": "...",
  • "inviteeId": "...",
  • "membershipInvitationId": "...",
  • "version": 12345
}

Response samples

Content type
application/json
"string"

Verify whether the inviteeEmail of the indicated MembershipInvitation is associated with the authenticated user.

Verify whether the inviteeEmail of the indicated MembershipInvitation is associated with the authenticated user.

If it is, the response body will contain an InviteeVerificationSignedToken. If it is not, a response status 403 Forbidden will be returned. InviteeVerificationSignedTokens generated by this service expire 24 hours from creation.

See https://sagebionetworks.jira.com/wiki/spaces/PLFM/pages/143628166/Invite+a+new+user+to+join+a+team for more information.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the invitation.

Responses

Response samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "hmac": "...",
  • "inviteeId": "...",
  • "membershipInvitationId": "...",
  • "version": 12345
}

Retrieve the number of pending Membership Invitations.

Retrieve the number of pending Membership Invitations

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "count": 12345
}

Retrieve the open invitations from a Team, optionally filtering by the invitee.

Retrieve the open invitations from a Team, optionally filtering by the invitee. An invitation is only open if it has not expired and if the user has not joined the Team. Note: certain fields may be omitted when returned if the field value is null

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

query Parameters
inviteeId
string

the ID of the Synapse user to which invitations have been extended

limit
integer [ 10 .. 100 ]
Default: 10

the maximum number of invitations to return

offset
integer >= 0
Default: 0

the starting index of the returned results

Responses

Response samples

Content type
application/json
{
  • "effectiveSchema": "...",
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Retrieve the open invitations to a user, optionally filtering by the Team of origin.

Retrieve the open invitations to a user, optionally filtering by the Team of origin. An invitation is only open if it has not expired and if the user has not joined the Team. Note: certain fields may be omitted when returned if the field value is null

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Synapse user.

query Parameters
limit
integer
Default: 10

the maximum number of invitations to return.

offset
integer
Default: 0

the starting index of the returned results.

teamId
string

the ID of the Team extending the invitations

Responses

Response samples

Content type
application/json
{
  • "effectiveSchema": "...",
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Membership Request Services

The Membership Request Services create, retrieve and delete membership requests.

.

Create a membership request and send an email notification to the administrators of the team.

The Team must be specified. Optionally, the creator may include a message and/or expiration date for the request.

If no expiration date is specified then the request never expires.

Authorizations:
bearerAuth
query Parameters
acceptRequestEndpoint
string
Default: "https://www.synapse.org/#!SignedToken:JoinTeam/"

The portal end-point for one-click acceptance of the membership

request. A signed, serialized token is appended to create the complete: JoinTeamSignedToken

In normal operation, this parameter should be omitted.

notificationUnsubscribeEndpoint
string
Default: "https://www.synapse.org/#!SignedToken:Settings/"

The portal prefix for one-click email unsubscription.

A signed, serialized token is appended to create the complete: NotificationSettingsSignedToken

In normal operation, this parameter should be omitted.

Request Body schema: application/json
createdBy
string

The ID of the user that created this MembershipRequest.

createdOn
string

The date this MembershipRequest was created.

expiresOn
string

The date this MembershipRequest expires (optional).

id
string

The id of the MembershipRequest.

message
string

The request message (optional).

teamId
string

The id of the Team to which the request is sent.

userId
string

The id of the user for whom membership is requested.

Responses

Request samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "id": "...",
  • "message": "...",
  • "teamId": "...",
  • "userId": "..."
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "id": "...",
  • "message": "...",
  • "teamId": "...",
  • "userId": "..."
}

Delete a request

Delete a request

Note: The client must be the creator of the membership request to make this request.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID for a membership request.

Responses

Retrieve an request by ID

Retrieve an request by ID

Note: The client must be the creator of the membership request to make this request.'

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID for a membership request.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "id": "...",
  • "message": "...",
  • "teamId": "...",
  • "userId": "..."
}

Get pending Membership Requests count

Retrieve the number of pending Membership Requests for teams that user is admin

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "count": 12345
}

Retrieve the open requests submitted to a Team, optionally filtering by the requester.

Retrieve the open requests submitted to a Team, optionally filtering by the requester. An request is only open if it has not expired and if the requester has not been added the Team.

Service Limits

resource limit
The maximum frequency this method can be called 40 calls per minute

'
Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

the maximum number of requests to return (default 10)

offset
integer >= 0
Default: 0

the starting index of the returned results (default 0)

requestorId
string

the ID of the user requesting admission to the Team

Responses

Response samples

Content type
application/json
{
  • "effectiveSchema": "...",
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Retrieve the open requests submitted by a user, optionally filtering by the Team.

Retrieve the open requests submitted by a user, optionally filtering by the Team. An request is only open if it has not expired and if the requester has not been added the Team. Note: The 'id' in the URI must be the same ID as that of the authenticated user issuing the request.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Synapse user.

query Parameters
limit
integer
Default: 10

the maximum number of requests to return

offset
integer >= 0
Default: 0

the starting index of the returned results.

teamId
string

ID of a Synapse Team.

Responses

Response samples

Content type
application/json
{
  • "effectiveSchema": "...",
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Message Services

Provides REST APIs for sending messages to other Synapse users and for commenting on Synapse entities.

Adds the owner of the given entity as an additional recipient of the message.

Adds the owner of the given entity as an additional recipient of the message.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an Entity.

Request Body schema: application/json
bcc
string

The email addresses in the 'bcc' field of the email message

cc
string

The email addresses in the 'cc' field of the email message

createdBy
string

The unique identifier of the sender of this message

createdOn
string

When this message was created

fileHandleId
string

The S3 file handle storing the body of this message. Note: The file's mime type should be 'text/plain' or 'text/html'. If no character encoding is specified, then UTF-8 is assumed.

id
string

The unique identifier of the message or comment

inReplyTo
string

The unique identifier of the message being replied to. Can be null

inReplyToRoot
string

The unique identifier of the root message being replied to

isNotificationMessage
boolean

A notification message is sent from a noreply email address, delivery failures are not sent back to the sender

notificationUnsubscribeEndpoint
string

the portal prefix for one-click email unsubscription. A signed, serialized token is appended to create the complete URL. If omitted, the default endpoint will be used.

recipients
Array of strings

The unique identifiers of the intended recipients of a message

subject
string

Topic of this message. Optional

to
string

The email addresses in the 'to' field of the email message

userProfileSettingEndpoint
string

the portal link to user profile setting page. If omitted, the default endpoint will be used.

withProfileSettingLink
boolean

should the user profile setting link be included in the email?

withUnsubscribeLink
boolean

should the unsubscribe link be included in the email?

Responses

Request samples

Content type
application/json
{
  • "bcc": "...",
  • "cc": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "fileHandleId": "...",
  • "id": "...",
  • "inReplyTo": "...",
  • "inReplyToRoot": "...",
  • "isNotificationMessage": true,
  • "notificationUnsubscribeEndpoint": "...",
  • "recipients": [
    ],
  • "subject": "...",
  • "to": "...",
  • "userProfileSettingEndpoint": "...",
  • "withProfileSettingLink": true,
  • "withUnsubscribeLink": true
}

Response samples

Content type
application/json
{
  • "bcc": "...",
  • "cc": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "fileHandleId": "...",
  • "id": "...",
  • "inReplyTo": "...",
  • "inReplyToRoot": "...",
  • "isNotificationMessage": true,
  • "notificationUnsubscribeEndpoint": "...",
  • "recipients": [
    ],
  • "subject": "...",
  • "to": "...",
  • "userProfileSettingEndpoint": "...",
  • "withProfileSettingLink": true,
  • "withUnsubscribeLink": true
}

Send a message

Sends a message.

The "fileHandleId" field should point to a plain text file containing the body of the message. The file should be uploaded prior to this call.

The "recipients" field should hold a set of IDs corresponding to the recipients of the message.

All other fields are optional, including the "subject" field.

To chain messages together into a conversation, specify the message you are replying to via the "inReplyTo" field.

See the MessageToUser, MessageContent, and MessageRecipientSet schema for more information.

In most cases, message delivery is asynchronous to message creation.

i.e. It may take several seconds for a message to appear in a user's inbox.

Notes:

Unauthorized delivery, such as messaging a team you are not affiliated with, will result in a bounce message being sent to your email.

There are limits on the number of message recipients you can specify (50) and the rate at which you can send messages (10 per minute). Neither these restrictions, nor the restriction that you can''t message a Team with which you are unaffiliated, apply if you are a member of the Trusted Message Senders Team.

Authorizations:
bearerAuth
Request Body schema: application/json
bcc
string

The email addresses in the 'bcc' field of the email message

cc
string

The email addresses in the 'cc' field of the email message

createdBy
string

The unique identifier of the sender of this message

createdOn
string

When this message was created

fileHandleId
string

The S3 file handle storing the body of this message. Note: The file's mime type should be 'text/plain' or 'text/html'. If no character encoding is specified, then UTF-8 is assumed.

id
string

The unique identifier of the message or comment

inReplyTo
string

The unique identifier of the message being replied to. Can be null

inReplyToRoot
string

The unique identifier of the root message being replied to

isNotificationMessage
boolean

A notification message is sent from a noreply email address, delivery failures are not sent back to the sender

notificationUnsubscribeEndpoint
string

the portal prefix for one-click email unsubscription. A signed, serialized token is appended to create the complete URL. If omitted, the default endpoint will be used.

recipients
Array of strings

The unique identifiers of the intended recipients of a message

subject
string

Topic of this message. Optional

to
string

The email addresses in the 'to' field of the email message

userProfileSettingEndpoint
string

the portal link to user profile setting page. If omitted, the default endpoint will be used.

withProfileSettingLink
boolean

should the user profile setting link be included in the email?

withUnsubscribeLink
boolean

should the unsubscribe link be included in the email?

Responses

Request samples

Content type
application/json
{
  • "bcc": "...",
  • "cc": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "fileHandleId": "...",
  • "id": "...",
  • "inReplyTo": "...",
  • "inReplyToRoot": "...",
  • "isNotificationMessage": true,
  • "notificationUnsubscribeEndpoint": "...",
  • "recipients": [
    ],
  • "subject": "...",
  • "to": "...",
  • "userProfileSettingEndpoint": "...",
  • "withProfileSettingLink": true,
  • "withUnsubscribeLink": true
}

Response samples

Content type
application/json
{
  • "bcc": "...",
  • "cc": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "fileHandleId": "...",
  • "id": "...",
  • "inReplyTo": "...",
  • "inReplyToRoot": "...",
  • "isNotificationMessage": true,
  • "notificationUnsubscribeEndpoint": "...",
  • "recipients": [
    ],
  • "subject": "...",
  • "to": "...",
  • "userProfileSettingEndpoint": "...",
  • "withProfileSettingLink": true,
  • "withUnsubscribeLink": true
}

Get the specified message.

Fetches the specified message.

The authenticated user must be either the sender or receiver of the message.

Authorizations:
bearerAuth
path Parameters
messageId
required
string

The ID of the message.

Responses

Response samples

Content type
application/json
{
  • "bcc": "...",
  • "cc": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "fileHandleId": "...",
  • "id": "...",
  • "inReplyTo": "...",
  • "inReplyToRoot": "...",
  • "isNotificationMessage": true,
  • "notificationUnsubscribeEndpoint": "...",
  • "recipients": [
    ],
  • "subject": "...",
  • "to": "...",
  • "userProfileSettingEndpoint": "...",
  • "withProfileSettingLink": true,
  • "withUnsubscribeLink": true
}

Retrieves messages belonging to the same thread as the given message.

Retrieves messages belonging to the same thread as the given message.

The current authenticated user will be either the sender or receiver of all returned messages.

By default, the most recent messages are returned first. To flip the ordering, set the "descending" parameter to "false". To change the way the messages are ordered, set the "orderBy" parameter to either "SEND_DATE" or "SUBJECT".

Authorizations:
bearerAuth
path Parameters
messageId
required
string

The ID of the message.

query Parameters
descending
boolean
Default: true

If true, returns the most recent messages.

limit
integer >= 10
Default: 10

Limits the number of messages

offset
integer >= 0
Default: 0

The offset index determines where this page will start from.

orderBy
string
Default: "SEND_DATE"
Enum: "SUBJECT" "SEND_DATE"

Order by

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Get the actual URL of the file associated with the message.

Get the actual URL of the file associated with the message

Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if the caller meets all of the download requirements.

Authorizations:
bearerAuth
path Parameters
messageId
required
string

The ID of the message.

query Parameters
redirect
boolean

When set to false, the URL will be returned as text/plain instead of redirecting.'

Responses

Response samples

Content type
application/json
"string"

Forwards a message to the specified set of recipients.

Forwards a message to the specified set of recipients.

The authenticated user must be either the sender or receiver of the forwarded message.

Authorizations:
bearerAuth
path Parameters
messageId
required
string

The ID of the message.

Request Body schema: application/json
recipients
Array of strings

The unique identifiers of the intended recipients of a message

Responses

Request samples

Content type
application/json
{
  • "recipients": [
    ]
}

Response samples

Content type
application/json
{
  • "bcc": "...",
  • "cc": "...",
  • "createdBy": "...",
  • "createdOn": "...",
  • "fileHandleId": "...",
  • "id": "...",
  • "inReplyTo": "...",
  • "inReplyToRoot": "...",
  • "isNotificationMessage": true,
  • "notificationUnsubscribeEndpoint": "...",
  • "recipients": [
    ],
  • "subject": "...",
  • "to": "...",
  • "userProfileSettingEndpoint": "...",
  • "withProfileSettingLink": true,
  • "withUnsubscribeLink": true
}

Retrieves the current authenticated user's inbox.

Retrieves the current authenticated user's inbox.

It may take several seconds for a message to appear in the inbox after creation. By default, the most recent unread messages are returned first. To flip the ordering, set the "descending" parameter to "false". To change the way the messages are ordered, set the "orderBy" parameter to either "SEND_DATE" or "SUBJECT".

To retrieve messages that have been read or archived, set the "inboxFilter" parameter to a comma-separated list of values defined in the MessageStatusType

Authorizations:
bearerAuth
query Parameters
descending
boolean
Default: true

By default, returns most recent unread messages.

inboxFilter
string
Default: "UNREAD"

Inbox filter

limit
integer >= 10
Default: 10

Limits the number of messages

offset
integer >= 0
Default: 0

The offset index determines where this page will start from.

orderBy
string
Default: "SEND_DATE"
Enum: "SUBJECT" "SEND_DATE"

Order by

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "effectiveSchema": "...",
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Retrieves the current authenticated user's outbox.

Retrieves the current authenticated user''s outbox.

By default, the most recent messages are returned first. To flip the ordering, set the "descending" parameter to "false". To change the way the messages are ordered, set the "orderBy" parameter to either "SEND_DATE" or "SUBJECT".

Authorizations:
bearerAuth
query Parameters
descending
boolean
Default: true

By default, the most recent message are returned.

limit
integer >= 10
Default: 10

Limits the number of messages

offset
integer >= 0
Default: 0

The offset index determines where this page will start from.

orderBy
string
Default: "SEND_DATE"
Enum: "SUBJECT" "SEND_DATE"

Order by

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Updates the current status of a message relative to the current authenticated user.

Updates the current status of a message relative to the current authenticated user.

Note: the "recipientId" field of the request body will be ignored.'

Authorizations:
bearerAuth
Request Body schema: application/json
messageId
string

The unique identifier of the message.

recipientId
string

The unique identifier of the recipient of this message.

status
string (MessageStatusType)
Enum: "READ" "UNREAD" "ARCHIVED"

The status of the message, from the RECIPIENT'S standpoint

Responses

Request samples

Content type
application/json
{
  • "messageId": "...",
  • "recipientId": "...",
  • "status": "ARCHIVED"
}

Response samples

Content type
application/json
"string"

Table Services

A Synapse TableEntity model object represents the metadata of a table. Each TableEntity is defined by a list of ColumnModel IDs. Use POST /column to create new ColumnModel objects. Each ColumnModel object is immutable, so to change a column of a table a new column must be added and the old column must be removed. TableEntities can be created, updated, read and deleted like any other entity.

Given the ID of a.

Given the ID of a TableEntity, get its list of <ahref="${org.sagebionetworks.repo.model.table.ColumnModel}">ColumnModels that are currently assigned to the table.

Service Limits

resource limit
The maximum frequency this method can be called 6 calls per minute

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a Table.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Get the actual URL of the file associated with a specific version of a row and file handle column.

Get the actual URL of the file associated with a specific version of a row and file handle column.

Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if the caller meets all of the download requirements.

Authorizations:
bearerAuth
path Parameters
columnId
required
string

The ID of the Table column

id
required
string

The ID of the FileEntity to get.

rowId
required
number

The ID of the Table Row

versionNumber
required
number

The version of the Table Row

query Parameters
redirect
boolean

When set to false, the URL will be returned as text/plain instead of redirecting.

Responses

Response samples

Content type
application/json
"string"

Get the preview URL of the file associated with a specific version of a row and file handle column.

Get the preview URL of the file associated with a specific version of a row and file handle column.

Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if the caller meets all of the download requirements.

Authorizations:
bearerAuth
path Parameters
columnId
required
string

The ID of the Table column

id
required
string

The ID of the FileEntity to get.

rowId
required
number

The ID of the Table Row

versionNumber
required
number

The version of the Table Row

query Parameters
redirect
boolean

When set to false, the URL will be returned as text/plain instead of redirecting.

Responses

Response samples

Content type
application/json
"string"

Asynchronously get the results of a csv download started with.

Asynchronously get the results of a csv download started with POST

Note: When the result is not ready yet, this method will return a status code of 202 (ACCEPTED) and the response body will be a AsynchronousJobStatus

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a TableEntity.

asyncToken
required
string

Async Token

Responses

Response samples

Content type
application/json
{
  • "concreteType": "...",
  • "etag": "...",
  • "headers": [
    ],
  • "resultsFileHandleId": "...",
  • "tableId": "..."
}

Asynchronously start a csv download.

Asynchronously start a csv download. Use the returned job id and /entity/{id}/table/download/csv/async/get to get the results of the query

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a TableEntity.

Request Body schema: application/json
additionalFilters
Array of objects (QueryFilter)

Appends additional filters to the SQL query. These are applied before facets. Filters within the list have an AND relationship. If a WHERE clause already exists on the SQL query or facets are selected, it will also be ANDed with the query generated by these additional filters.

includeEntityEtag
boolean

Optional, default false. When true, a query results against views will include the Etag of each entity in the results. Note: The etag is necessary to update Entities in the view.

limit
required
integer

The optional limit to the results

DownloadFromTableRequest
DownloadFromTableRequest
offset
integer

The optional offset into the results

Array of objects (FacetColumnRequest)

The selected facet filters.

Array of objects (SortItem)

To sort values

sql
string

The SQL query string.

concreteType
string

Concrete Type

object (CsvTableDescriptor)

The description of a csv for upload or download.

entityId
string

Entity Id

includeRowIdAndRowVersion
boolean
Default: true

Should the first two columns contain the row ID and row version? The default value is 'true'.

writeHeader
boolean
Default: true

Should the first line contain the columns names as a header in the resulting file? Set to 'true' to include the headers else, 'false'. The default value is 'true'.

Responses

Request samples

Content type
application/json
{
  • "additionalFilters": [
    ],
  • "includeEntityEtag": true,
  • "limit": "DownloadFromTableRequest",
  • "offset": 12345,
  • "selectedFacets": [
    ],
  • "sort": [
    ],
  • "sql": "...",
  • "concreteType": "string",
  • "csvTableDescriptor": {
    },
  • "entityId": "string",
  • "includeRowIdAndRowVersion": true,
  • "writeHeader": true
}

Response samples

Content type
application/json
{
  • "token": "..."
}

.

This method is used to get file handle information for rows in a TableEntity. The columns in the passed in RowReferenceSet need to be FILEHANDLEID columns and the rows in the passed in RowReferenceSet need to exists (a 400 will be returned if a row ID is provided that does not actually exist). The order of the returned rows of file handles is the same as the order of the rows requested, and the order of the file handles in each row is the same as the order of the columns requested.

Note: The caller must have the READ permission on the TableEntity to make this call.

Service Limits

resource limit
The maximum frequency this method can be called 1 calls per second
Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a TableEntity.

Request Body schema: application/json
etag
string

When a RowReferenceSet is returned from a table update, this will be set to the current etag of the table.

Array of objects (SelectColumn)

The list of ColumnModels ID that describes the rows of this set.

Array of objects (RowReference)

Each RowReference of this list refers to a single version of a single row of a TableEntity.

tableId
string

The ID of the TableEntity than owns these rows

Responses

Request samples

Content type
application/json
{
  • "etag": "...",
  • "headers": [
    ],
  • "rows": [
    ],
  • "tableId": "..."
}

Response samples

Content type
application/json
{
  • "headers": [
    ],
  • "rows": [
    ],
  • "tableId": "..."
}

Asynchronously get the results of a query started with.

Asynchronously get the results of a query started with POST /entity/{id}/table/query/async/start

Note: When the result is not ready yet, this method will return a status code of 202 (ACCEPTED) and the response body will be a AsynchronousJobStatus object.

Authorizations:
bearerAuth
path Parameters
asyncToken
required
string

Async Token

id
required
string

The ID of the TableEntity.

Responses

Response samples

Content type
application/json
{
  • "columnModels": [
    ],
  • "concreteType": "...",
  • "facets": [
    ],
  • "lastUpdatedOn": "...",
  • "maxRowsPerPage": 12345,
  • "queryCount": 12345,
  • "queryResult": {
    },
  • "selectColumns": [
    ],
  • "sumFileSizes": {
    }
}

Asynchronously start a query.

Asynchronously start a query. Use the returned job id and GET /entity/{id}/table/query/async/get to get the results of the query

Using a 'SQL like' syntax, query the current version of the rows in a single table. The following pseudo-syntax is the basic supported format:

SELECT

[ALL | DISTINCT] select_expr [, select_expr ...]

FROM synapse_table_id

[WHERE where_condition]

[GROUP BY {col_name [, [col_name * ...] }

[ORDER BY {col_name [ [ASC | DESC] [, col_name [ [ASC | DESC]]}

[LIMIT row_count [ OFFSET offset ]]

Note: Sub-queries and joining tables is not supported.

This services depends on an index that is created/update asynchronously from table creation and update events. This means there could be short window of time when the index is inconsistent with the true state of the table. When the index is out-of-synch, then a status code of 202 (ACCEPTED) will be returned and the response body will be a TableStatus object. The TableStatus will indicates the current status of the index including how much work is remaining until the index is consistent with the truth of the table.

The 'partsMask' is an integer "mask" that can be combined into to request any desired part. As of this writing, the mask is defined as follows QueryBundleRequest

  • Query Results (queryResults) = 0x1
  • Query Count (queryCount) = 0x2
  • Select Columns (selectColumns) = 0x4
  • Max Rows Per Page (maxRowsPerPage) = 0x8
  • The Table Columns (columnModels) = 0x10
  • Facet statistics for each faceted column (facetStatistics) = 0x20
  • The sum of the file sizes (sumFileSizesBytes) = 0x40

For example, to request all parts, the request mask value should be:
0x1 OR 0x2 OR 0x4 OR 0x8 OR 0x10 OR 0x20 OR 0x40 = 0x7F.

Note: The caller must have the READ permission on the TableEntity to make this call.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a TableEntity.

Request Body schema: application/json
concreteType
string

Concrete Type

entityId
string

Entity Id

partMask
integer

Optional, default all. The 'partsMask' is an integer mask that can be combined into to request any desired part. The mask is defined as follows:

  • Query Results (queryResults) = 0x1
  • Query Count (queryCount) = 0x2
  • Select Columns (selectColumns) = 0x4
  • Max Rows Per Page (maxRowsPerPage) = 0x8
  • The Table Columns (columnModels) = 0x10
  • Facet statistics for each faceted column (facetStatistics) = 0x20
  • The sum of the file sizes (sumFileSizesBytes) = 0x40
object (Query)

Query

Responses

Request samples

Content type
application/json
{
  • "concreteType": "...",
  • "entityId": "...",
  • "partMask": 1,
  • "query": {
    }
}

Response samples

Content type
application/json
{
  • "token": "..."
}

Request to create a new snapshot of a table.

Request to create a new snapshot of a table. The provided comment, label, and activity ID will be applied to the current version thereby creating a snapshot and locking the current version. After the snapshot is created a new version will be started with an 'in-progress' label.

NOTE: This service is for TableEntity only. Snapshots of EntityView require asynchronous processing and can be created via: POST /entity/{id}/table/transaction/async/start

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a Table Entity.

Request Body schema: application/json
snapshotActivityId
string

Optional. If createNewSnapshot=true, the Activity ID to be applied to the snapshot version. Null by default

snapshotComment
string

Optional. If createNewSnapshot=true, the comment to be applied to the snapshot version. Null by default

snapshotLabel
string

Optional. If createNewSnapshot=true, the label to be applied to the snapshot version. Null by default

Responses

Request samples

Content type
application/json
{
  • "snapshotActivityId": "...",
  • "snapshotComment": "...",
  • "snapshotLabel": "..."
}

Response samples

Content type
application/json
{
  • "snapshotVersionNumber": 12345
}

Asynchronously get the results of a table update transaction started with.

Asynchronously get the results of a table update transaction started with POST /entity/{id}/table/transaction/async/start

Note: When the result is not ready yet, this method will return a status code of 202 (ACCEPTED) and the response body will be a AsynchronousJobStatus object.

Authorizations:
bearerAuth
path Parameters
asyncToken
required
string

The token returned when the job was started.

id
required
string

The ID of a Table entity.

Responses

Response samples

Content type
application/json
{
  • "concreteType": "...",
  • "results": [
    ],
  • "snapshotVersionNumber": 12345
}

Start a table update job that will attempt to make all of the requested changes in a single transaction.

Start a table update job that will attempt to make all of the requested changes in a single transaction. All updates will either succeed or fail as a unit. All update requests must be for the same table.

Note: The caller must have the UPDATE permission on the TableEntity to make this call.

Service Limits

resource limit
The maximum size of a PartialRow change 2 MB
The maximum size of a CSV that can be appended to a table 1 GB

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a Table Entity.

Request Body schema: application/json
Array of objects (TableUpdateRequest)

List of changes that describes schema and/or row changes to a table.

concreteType
string

Concrete Type

createSnapshot
boolean

When set to 'true', a snapshot of the table will be created after the change from this transaction request are applied to the table.

entityId
string

Entity Id

object (SnapshotRequest)

Request to create a new snapshot of a table or view. The provided comment, label, and activity ID will be applied to the current version thereby creating a snapshot and locking the current version. After the snapshot is created a new version will be started with an 'in-progress' label.

Responses

Request samples

Content type
application/json
{
  • "changes": [
    ],
  • "concreteType": "...",
  • "createSnapshot": true,
  • "entityId": "...",
  • "snapshotOptions": {
    }
}

Response samples

Content type
application/json
{
  • "token": "..."
}

Team Services

Teams are groups of users.

Create a new Team.

Create a new Team.

To specify a Team icon, the icon file must first be uploaded to Synapse as FileHandle. The FileHandle ID can then be put into the Team's icon field.

Authorizations:
bearerAuth
Request Body schema: application/json
canPublicJoin
boolean

true for teams which members can join without an invitation or approval

createdBy
string

The ID of the user that created this Team.

createdOn
string

The date this Team was created.

description
string

A short description of this Team.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time a Team is updated it is used to detect when a client's current representation of a Team is out-of-date.

icon
string

fileHandleId for icon image of the Team

id
string

The id of the Team.

modifiedBy
string

The ID of the user that last modified this Team.

modifiedOn
string

The date this Team was last modified.

name
string

The name of the Team.

Responses

Request samples

Content type
application/json
{
  • "canPublicJoin": true,
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "icon": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "..."
}

Response samples

Content type
application/json
{
  • "canPublicJoin": true,
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "icon": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "..."
}

Update the Team metadata for the specified Team.

Update the Team metadata for the specified Team. Note: The client must be a Team administrator to make this request.

Authorizations:
bearerAuth
Request Body schema: application/json

the new metadata for the Team

canPublicJoin
boolean

true for teams which members can join without an invitation or approval

createdBy
string

The ID of the user that created this Team.

createdOn
string

The date this Team was created.

description
string

A short description of this Team.

etag
string

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time a Team is updated it is used to detect when a client's current representation of a Team is out-of-date.

icon
string

fileHandleId for icon image of the Team

id
string

The id of the Team.

modifiedBy
string

The ID of the user that last modified this Team.

modifiedOn
string

The date this Team was last modified.

name
string

The name of the Team.

Responses

Request samples

Content type
application/json
{
  • "canPublicJoin": true,
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "icon": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "..."
}

Response samples

Content type
application/json
{
  • "canPublicJoin": true,
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "icon": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "..."
}

Retrieve a paginated list of Teams in alphabetical order by Team name.

Retrieve a paginated list of Teams matching the supplied name fragment (optional), in alphabetical order by Team name.


Note: This service has JSONP support: If the request parameter "callback=jsMethod" is included (where 'jsMethod' is any function name you wish), then the response body will be wrapped in "jsMethod(...);".

Authorizations:
bearerAuth
query Parameters
fragment
string

a prefix of the Team name, or a prefix of any sub-string in the name preceded by a space. If omitted, all Teams are returned.

limit
integer [ 10 .. 50 ]
Default: 10

the maximum number of Teams to return.

offset
integer >= 0
Default: 0

the starting index of the returned results (default 0)

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Delete the Team.

Delete the Team. Note: The client must be a Team administrator to make this request.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

Responses

Retrieve the metadata for a specified Team.

Retrieve the metadata for a specified Team.

Service Limits

resource limit
The maximum frequency this method can be called 1 calls per second

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

Responses

Response samples

Content type
application/json
{
  • "canPublicJoin": true,
  • "createdBy": "...",
  • "createdOn": "...",
  • "description": "...",
  • "etag": "...",
  • "icon": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "...",
  • "name": "..."
}

Retrieve the AccessControlList for a specified Team.

Retrieve the AccessControlList for a specified Team.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

Responses

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Retrieve the download URL for the Team icon, or receive a redirect response to said URL

Retrieve the download URL for the Team icon, or receive a redirect response to said URL.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

query Parameters
redirect
boolean

if true or omitted, then redirect to the URL. If false then simply return the URL.

Responses

Response samples

Content type
application/json
"string"

Retrieve the download URL for the Team icon preview, or receive a redirect response to said URL.

Retrieve the download URL for the Team icon preview, or receive a redirect response to said URL.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

query Parameters
redirect
boolean

if true or omitted, then redirect to the URL. If false then simply return the URL.

Responses

Response samples

Content type
application/json
"string"

Remove the given member from the specified Team.

Remove the given member from the specified Team. Note: The client must either be a Team administrator or the member being removed.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

principalId
required
string

the member's principal ID

Responses

.

'

Service Limits

resource limit
The maximum frequency this method can be called 1 calls per second

'
Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

principalId
required
string

the member's principal ID

Responses

Response samples

Content type
application/json
{
  • "isAdmin": true,
  • "member": {
    },
  • "teamId": "..."
}

Add a member to the Team.

Add a member to the Team.

If the one making the request is the user to be added, then the user must have an open invitation from the Team. If the one making the request is an administrator on the Team, then there must be a pending request from the user to the Team, asking to be added. If both teamEndpoint and notificationUnsubscribeEndpoint are provided, notification email(s) will be sent to the appropriate parties.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

principalId
required
string

the member's principal ID

query Parameters
notificationUnsubscribeEndpoint
string

the portal prefix for one-click email unsubscription. A signed, serialized token is appended to create the complete URL: <ahref="${org.sagebionetworks.repo.model.message.NotificationSettingsSignedToken}">NotificationSettingsSignedToken'

teamEndpoint
string

the portal prefix for the Team URL. The team ID is appended to create the complete URL.

Responses

Retrieve the Team Membership Status bundle for a team and user.

Retrieve the Team Membership Status bundle for a team and user. This says whether a user is a member of a Team, whether there are outstanding membership requests or invitations, and whether the client making the request can add the given user to the given Team.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

principalId
required
string

the member's principal ID

Responses

Response samples

Content type
application/json
{
  • "canJoin": true,
  • "canSendEmail": true,
  • "hasOpenInvitation": true,
  • "hasOpenRequest": true,
  • "hasUnmetAccessRequirement": true,
  • "isMember": true,
  • "membershipApprovalRequired": true,
  • "teamId": "...",
  • "userId": "..."
}

Returns the TeamMember info for a team and a given list of members' principal IDs.

Returns the TeamMember info for a team and a given list of members' principal IDs. Invalid IDs in the list are ignored: The results list is simply smaller than the list of IDs passed in.

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

Request Body schema: application/json
list
Array of integers

List of IDs

Responses

Request samples

Content type
application/json
{
  • "list": [
    ]
}

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Update the Access Control List for the specified Team.

Update the Access Control List for the specified Team.

Authorizations:
bearerAuth
Request Body schema: application/json

the updated Access Control List

createdBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

creationDate
string

Created Date

etag
string

Synapse etag value

id
string

The entity id

modifiedBy
string

UNUSED -- maintained only for backwards compatibility with archived objects

modifiedOn
string

UNUSED -- maintained only for backwards compatibility with archived objects

Array of objects (ResourceAccess)

The list of principals who can access the data with the allowed types of access for each.

Responses

Request samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Response samples

Content type
application/json
{
  • "createdBy": "...",
  • "creationDate": "12345",
  • "etag": "...",
  • "id": "...",
  • "modifiedBy": "...",
  • "modifiedOn": "12345",
  • "resourceAccess": [
    ]
}

Retrieve a list of Teams given their IDs.

Retrieve a list of Teams given their IDs. Invalid IDs in the list are ignored: The results list is simply smaller than the list of IDs passed in.

Authorizations:
bearerAuth
Request Body schema: application/json
list
Array of integers

List of IDs

Responses

Request samples

Content type
application/json
{
  • "list": [
    ]
}

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Add a member to the Team.

Add a member to the Team. Note: The request is authenticated by a hash message authentication code in the request body, generated by Synapse. The intended use of this service is by the portal, completing a round trip with a 'one-click join-team' link provided to the user by Synapse via email. If both teamEndpoint and notificationUnsubscribeEndpoint are provided, notification email(s) will be sent to the appropriate parties.

Authorizations:
bearerAuth
query Parameters
notificationUnsubscribeEndpoint
string

notification unsubscribe endpoint

teamEndpoint
string

Team end point

Request Body schema: application/json
concreteType
string

Concrete Type

createdOn
string

The date-time the token was generated.

expiresOn
string

The date-time when this token expires.

hmac
string

The hash message authentication code for the message.

memberId
string

The ID of the new team member.

teamId
string

The ID of the team which the user was invited to join.

userId
string

The ID of the user who is acting to add the new member to the Team. The HMAC in the token authenticates that the request is being made by this user.'

version
integer

The version of the key used to generate the HMAC.

Responses

Request samples

Content type
application/json
{
  • "concreteType": "...",
  • "createdOn": "...",
  • "expiresOn": "...",
  • "hmac": "...",
  • "memberId": "...",
  • "teamId": "...",
  • "userId": "...",
  • "version": 12345
}

Response samples

Content type
application/json
{
  • "message": "..."
}

Retrieve a paginated list of Team members matching the supplied name prefix.

Retrieve a paginated list of Team members matching the supplied name prefix. If the prefix is omitted then all members are returned.


Note: This service has JSONP support: If the request parameter "callback=jsMethod" is included (where 'jsMethod' is any function name you wish), then the response body will be wrapped in "jsMethod(...);".

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

query Parameters
fragment
string

a prefix of the user's first or last name or email address

limit
integer [ 10 .. 50 ]
Default: 10

the maximum number of members to return.

memberType
string
Default: "ALL"
Enum: "ADMIN" "ALL" "MEMBER"

the type of team user to retrieve

offset
integer >= 0
Default: 0

the starting index of the returned results

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Retrieve the number of Team members matching the supplied name prefix.

Retrieve the number of Team members matching the supplied name prefix. If the prefix is omitted then the number of members in the team is returned.


Note: This service has JSONP support: If the request parameter "callback=jsMethod" is included (where 'jsMethod' is any function name you wish), then the response body will be wrapped in "jsMethod(...);".

Authorizations:
bearerAuth
path Parameters
id
required
string

the ID of the Team.

query Parameters
fragment
string

a prefix of the user's first or last name or email address

Responses

Response samples

Content type
application/json
{
  • "count": 12345
}

Returns the TeamMember info for a user and a given list of Team IDs.

Returns the TeamMember info for a user and a given list of Team IDs. Not Found status is returned if the user ID is invalid, any of the Team IDs are invalid, or the user is not in any of the given teams.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Synapse user.

Request Body schema: application/json

Team IDs

list
Array of integers

List of IDs

Responses

Request samples

Content type
application/json
{
  • "list": [
    ]
}

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Retrieve a paginated list of Teams to which the given user belongs.

Retrieve a paginated list of Teams to which the given user belongs.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Synapse user.

query Parameters
limit
integer
Default: 10

the maximum number of Teams to return (default 10)

offset
integer >= 0
Default: 0

the starting index of the returned results (default 0)

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Retrieve a paginated list of IDs of Teams to which the given user belongs.

Retrieve a paginated list of IDs of Teams to which the given user belongs. If sorting is desired, both sort and ascending must be specified. If they are omitted, results are not sorted.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Synapse user.

query Parameters
ascending
boolean

the direction of sort: true for ascending, and false for descending

nextPageToken
string

controls pagination

sort
string
Value: "TEAM_NAME"

the field to sort the team IDs on. Available options TeamSortOrder

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "...",
  • "teamIds": [
    ]
}

Trash Services

The recycle bin (or trash can) is the special folder that holds the deleted entities for users.

Flags the specified entity for priority purge.

Flags the specified entity for priority purge. The entity will be deleted as soon as possible. Once purging is done, the entity will be permanently deleted from the system.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
"string"

Moves an entity and its descendants out of the trash can back to its original parent.

Moves an entity and its descendants out of the trash can back to its original parent. An exception is thrown if the original parent does not exist any more. In that case, please use PUT /trashcan/restored/{id}/{parentId} to restore to a new parent. In such a case you must be a member of the Synapse Access and Compliance Team.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
"string"

Moves an entity and its descendants out of the trash can to a new parent.

Moves an entity and its descendants out of the trash can to a new parent.

NOTE: This operation cannot be completed if the original parent has been deleted (unless the caller is a member of the Synapse Access and Compliance Team). The service will return a NotFoundException. This is because of the potential security hole arising from allowing access requirements on folders: If an entity is in a restricted folder and then deleted, it cannot be restored unless the new parent has the same restriction level as the original one.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of a deleted entity.

parentId
required
string

The ID of the new parent entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
"string"

Moves an entity and its descendants to the trash can.

Moves an entity and its descendants to the trash can.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of an entity.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
"string"

Retrieves the paginated list of trash entities deleted by the current user.

Retrieves the paginated list of trash entities deleted by the current user.

Authorizations:
bearerAuth
query Parameters
limit
integer [ 10 .. 100 ]
Default: 10

The maximum number of entities to retrieve per page.

offset
integer >= 0
Default: 0

Paginated results. Offset to the current page.

Request Body schema: application/json
object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "effectiveSchema": "...",
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

User Profile Services

Every Synapse user has an associated User Profile

Get all publicly available.

Get all publicly available UserProfile data in the system

Authorizations:
bearerAuth
query Parameters
ascending
boolean
Default: true

Used to indicate whether the sort direction is ascending or not.

limit
integer
Default: 100

Limits the number of items that will be fetched for this page

offset
integer
Default: 0

The offset index determines where this page will start from. An index of 0 is the first item.

sort
string

Used to indicate upon which field(s) to sort.

Request Body schema: application/json

Get all publicly available UserProfile data in the system

object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Get the user bundle of a specified user.

Get the user bundle of a specified user.

Note: Private fields (e.g. "rStudioUrl") are omitted unless the requester is the profile owner or an administrator.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the Synapse user.

query Parameters
mask
required
string

integer flag defining which components to include in the bundle

This integer is used as a bit-string of flags to specify which parts to include in the UserBundle. The mask is defined as follows:

  • UserProfile = 0x1
  • ORCID = 0x2
  • VerificationSubmission = 0x4
  • Is Certified = 0x8
  • Is Verified = 0x10
  • Is ACT Member = 0x20

Responses

Response samples

Content type
application/json
{
  • "ORCID": "...",
  • "isACTMember": true,
  • "isCertified": true,
  • "isVerified": true,
  • "userId": "...",
  • "userProfile": {
    },
  • "verificationSubmission": {
    }
}

Get the user bundle of the caller (my own bundle).

Get the user bundle of the caller (my own bundle).

Note: Private fields will be returned.

Authorizations:
bearerAuth
query Parameters
mask
required
string

integer flag defining which components to include in the bundle

This integer is used as a bit-string of flags to specify which parts to include in the UserBundle. The mask is defined as follows:

  • UserProfile = 0x1
  • ORCID = 0x2
  • VerificationSubmission = 0x4
  • Is Certified = 0x8
  • Is Verified = 0x10
  • Is ACT Member = 0x20

Responses

Response samples

Content type
application/json
{
  • "ORCID": "...",
  • "isACTMember": true,
  • "isCertified": true,
  • "isVerified": true,
  • "userId": "...",
  • "userProfile": {
    },
  • "verificationSubmission": {
    }
}

Get the user-groups in the system.

Get the user-groups in the system

Authorizations:
bearerAuth
query Parameters
ascending
boolean
Default: true

Return results in ascending order.

limit
integer
Default: 10

the maximum number of results to return.

offset
integer >= 0
Default: 0

the starting index of the returned results.

sort
string
Default: "NONE"

Sort results.

Request Body schema: application/json

Get the user-groups in the system

object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalNumberOfResults": 12345
}

Get Users and Groups that match the given prefix.

Get Users and Groups that match the given prefix.

Authorizations:
bearerAuth
query Parameters
limit
integer
Default: 10

Limits the number of items that will be fetched for this page.

offset
integer >= 10
Default: 0

The offset index determines where this page will start from. An index of 0 is the first item.

prefix
string

The name to search for.

typeFilter
string
Enum: "ALL" "TEAMS_ONLY" "USERS_ONLY"

Restrict the results to a type of principal. Available options: TypeFilter.'

Responses

Response samples

Content type
application/json
{
  • "children": [
    ],
  • "prefixFilter": "...",
  • "totalNumberOfResults": 12345
}

Get Users and Groups that match the given list of aliases.

Get Users and Groups that match the given list of aliases.

Authorizations:
bearerAuth
Request Body schema: application/json

The list of principal aliases to lookup. Each alias must be either a user name or team name. The maximum number of aliases per request is 100.

list
Array of strings

List of principal aliases

Responses

Request samples

Content type
application/json
{
  • "list": [
    ]
}

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Batch get UserGroupHeaders.

Batch get UserGroupHeaders. This fetches information about a collection of users or groups, specified by Synapse IDs.

Authorizations:
bearerAuth
query Parameters
ids
required
string

IDs are specified as request parameters at the end of the URL, separated by commas. For example: ids=1001,819

Request Body schema: application/json

Batch get UserGroupHeaders. This fetches information about a collection of users or groups, specified by Synapse IDs.

object (Empty)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "children": [
    ],
  • "prefixFilter": "...",
  • "totalNumberOfResults": 12345
}

Get the profile of the caller (my profile).

Get the profile of the caller (my profile).

Note: Private user profile fields will be returned.

'
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "RStudioUrl": "...",
  • "company": "...",
  • "createdOn": "...",
  • "displayName": "...",
  • "email": "...",
  • "emails": [
    ],
  • "etag": "...",
  • "firstName": "...",
  • "industry": "...",
  • "lastName": "...",
  • "location": "...",
  • "notificationSettings": {
    },
  • "openIds": [
    ],
  • "ownerId": "...",
  • "position": "...",
  • "preferences": [
    ],
  • "profilePicureFileHandleId": "...",
  • "summary": "...",
  • "teamName": "...",
  • "url": "...",
  • "userName": "..."
}

Batch get UserGroupHeaders.

Batch get UserGroupHeaders. This fetches information about a collection of users or groups, specified by Synapse IDs.'

Authorizations:
bearerAuth
Request Body schema: application/json

IDs are specified as request parameters at the end of the URL, separated by commas. For example: ids=1001,819

list
Array of integers

List of IDs

Responses

Request samples

Content type
application/json
{
  • "list": [
    ]
}

Response samples

Content type
application/json
{
  • "effectiveSchema": "...",
  • "list": [
    ]
}

Update your own profile.

Update your own profile

Note: The user associated with the UserProfile "ownerId" must match the identity of the caller, otherwise an Unauthorized response will occur.

Authorizations:
bearerAuth
Request Body schema: application/json
RStudioUrl
string

URL for RStudio server assigned to the user

company
string

This person's current affiliation

createdOn
string

The date this profile was created.

displayName
string
Deprecated

Will always be null.

email
string
Deprecated

Users can have more than one email. See emails

emails
Array of strings

The list of user email addresses registered to this user.

etag
string (Etag)

Synapse employs an Optimistic Concurrency Control (OCC) scheme to handle concurrent updates. Since the E-Tag changes every time an entity is updated it is used to detect when a client's current representation of an entity is out-of-date.

firstName
string

This person's given name (forename)

industry
string

The industry/discipline that this person is associated with

lastName
string

This person's family name (surname)

location
string

This person's location

object (Settings)

Contains a user's notification settings

openIds
Array of strings

'The list of OpenIds bound to this user's account.'

ownerId
string

'A foreign key to the ID of the 'principal' object for the user.'

position
string

This person's current position title

Array of objects (UserPreference)

User preferences

profilePicureFileHandleId
string

The FileHandle.id of the user's profile picture.

summary
string

A summary description about this person

teamName
string

This person's default team name

url
string

A link to more information about this person

userName
string

A name chosen by the user that uniquely identifies them.

Responses

Request samples

Content type
application/json
{
  • "RStudioUrl": "...",
  • "company": "...",
  • "createdOn": "...",
  • "displayName": "...",
  • "email": "...",
  • "emails": [
    ],
  • "etag": "...",
  • "firstName": "...",
  • "industry": "...",
  • "lastName": "...",
  • "location": "...",
  • "notificationSettings": {
    },
  • "openIds": [
    ],
  • "ownerId": "...",
  • "position": "...",
  • "preferences": [
    ],
  • "profilePicureFileHandleId": "...",
  • "summary": "...",
  • "teamName": "...",
  • "url": "...",
  • "userName": "..."
}

Response samples

Content type
application/json
{
  • "RStudioUrl": "...",
  • "company": "...",
  • "createdOn": "...",
  • "displayName": "...",
  • "email": "...",
  • "emails": [
    ],
  • "etag": "...",
  • "firstName": "...",
  • "industry": "...",
  • "lastName": "...",
  • "location": "...",
  • "notificationSettings": {
    },
  • "openIds": [
    ],
  • "ownerId": "...",
  • "position": "...",
  • "preferences": [
    ],
  • "profilePicureFileHandleId": "...",
  • "summary": "...",
  • "teamName": "...",
  • "url": "...",
  • "userName": "..."
}

Get the profile of a specified user.

Get the profile of a specified user.

Note: Private fields (e.g. "rStudioUrl") are omitted unless the requester is the profile owner or an administrator.

'
Authorizations:
bearerAuth
path Parameters
profileId
required
string

The ID of the Synapse user.

Responses

Response samples

Content type
application/json
{
  • "RStudioUrl": "...",
  • "company": "...",
  • "createdOn": "...",
  • "displayName": "...",
  • "email": "...",
  • "emails": [
    ],
  • "etag": "...",
  • "firstName": "...",
  • "industry": "...",
  • "lastName": "...",
  • "location": "...",
  • "notificationSettings": {
    },
  • "openIds": [
    ],
  • "ownerId": "...",
  • "position": "...",
  • "preferences": [
    ],
  • "profilePicureFileHandleId": "...",
  • "summary": "...",
  • "teamName": "...",
  • "url": "...",
  • "userName": "..."
}

Get the actual URL of the image file associated with a user's profile.

Get the actual URL of the image file associated with a user's profile.

Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if the caller meets all of the download requirements.

Authorizations:
bearerAuth
path Parameters
profileId
required
string

The ID of the Synapse user.

query Parameters
redirect
boolean

When set to false, the URL will be returned as text/plain instead of redirecting.

Responses

Response samples

Content type
application/json
"string"

Get the actual URL of the image file associated with a user's profile.

Get the actual URL of the image file associated with a user''s profile.

Note: This call will result in a HTTP temporary redirect (307), to the actual file URL if the caller meets all of the download requirements.

Authorizations:
bearerAuth
path Parameters
profileId
required
string

The ID of the Synapse user.

query Parameters
redirect
boolean

When set to false, the URL will be returned as text/plain instead of redirecting.

Responses

Response samples

Content type
application/json
"string"